Run on Event

This example assumes we have a task registered on a running worker.

Run-on-event allows you to trigger one or more tasks when a specific event occurs. This is useful when you need to execute a task in response to an ephemeral event where the result is not important. A few common use cases for event-triggered task runs are:

1. Running a task when an ephemeral event is received, such as a webhook or a message from a queue.
2. When you want to run multiple independent tasks in response to a single event. For instance, if you wanted to run a send_welcome_email task, and you also wanted to run a grant_new_user_credits task, and a reward_referral task, all triggered by the signup. In this case, you might declare all three of those tasks with an event trigger for user:signup, and then have them all kick off when that event happens.

Declaring Event Triggers

To run a task on an event, you need to declare the event that will trigger the task. This is done by declaring the on_events property in the task declaration.

event_workflow = hatchet.workflow(name="EventWorkflow", on_events=["user:create"])

export const lower = hatchet.workflow<Input, LowerOutput>({
  name: 'lower',
  onEvents: ['simple-event:create'],
});

const SimpleEvent = "simple-event:create"

func Lower(hatchet v1.HatchetClient) workflow.WorkflowDeclaration[EventInput, LowerTaskOutput] {
	return factory.NewTask(
		create.StandaloneTask{
			Name: "lower",
			OnEvents: []string{SimpleEvent},
		}, func(ctx worker.HatchetContext, input EventInput) (*LowerTaskOutput, error) {
			// Transform the input message to lowercase
			return &LowerTaskOutput{
				TransformedMessage: strings.ToLower(input.Message),
			}, nil
		},
		hatchet,
	)
}

Pushing an Event

You can push an event to the event queue by calling the push method on the Hatchet event client and providing the event name and payload.

hatchet.event.push("user:create", {})

const res = await hatchet.events.push<Input>('simple-event:create', {
  Message: 'hello',
});

err = hatchet.Events().Push(
	context.Background(),
	"simple-event:create",
	v1_workflows.SimpleInput{
		Message: "Hello, World!",
	},
)