Add to Cursor Add to Claude Copy for LLM View as MD

Event Trigger

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. See Event-Driven Systems for a detailed guide. A few common use cases for event-triggered task runs are:

Running a task when an ephemeral event is received, such as a webhook or a message from a queue.
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.

Event triggers evaluate tasks to run at the time of the event. If an event is received before the task is registered, the task will not be run.

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.

examples/python/events/worker.py

EVENT_KEY = "user:create"
SECONDARY_KEY = "foobarbaz"
WILDCARD_KEY = "subscription:*"


class EventWorkflowInput(BaseModel):
    should_skip: bool


event_workflow = hatchet.workflow(
    name="EventWorkflow",
    on_events=[EVENT_KEY, SECONDARY_KEY, WILDCARD_KEY],
    input_validator=EventWorkflowInput,
)

examples/typescript/on_event/workflow.ts

export const lower = hatchet.workflow<Input, LowerOutput>({
  name: 'lower',
  // 👀 Declare the event that will trigger the workflow
  onEvents: ['simple-event:create'],
});

examples/go/on-event/main.go

const SimpleEvent = "simple-event:create"

func Lower(client *hatchet.Client) *hatchet.StandaloneTask {
	return client.NewStandaloneTask(
		"lower", func(ctx hatchet.Context, input EventInput) (*LowerTaskOutput, error) {
			return &LowerTaskOutput{
				TransformedMessage: strings.ToLower(input.Message),
			}, nil
		},
		hatchet.WithWorkflowEvents(SimpleEvent),
	)
}

The Ruby SDK is in early access, and may change. We'd love your feedback!

examples/ruby/events/worker.rb

EVENT_KEY = "user:create"
SECONDARY_KEY = "foobarbaz"
WILDCARD_KEY = "subscription:*"

EVENT_WORKFLOW = HATCHET.workflow(
  name: "EventWorkflow",
  on_events: [EVENT_KEY, SECONDARY_KEY, WILDCARD_KEY]
)

Note: Multiple tasks can be triggered by the same event.

As of engine version 0.65.0, Hatchet supports wildcard event triggers using the * wildcard pattern. For example, you could register subscription:* as your event key, which would match incoming events like subcription:create, subscription:renew, subscription:cancel, and so on.

Pushing Events Event Filters

We use cookies

Event Trigger

Declaring Event Triggers