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:

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_workflow = hatchet.workflow(
    name="EventWorkflow",
    on_events=[EVENT_KEY, SECONDARY_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/workflows/on-event.go

const SimpleEvent = "simple-event:create"

func Lower(hatchet v1.HatchetClient) workflow.WorkflowDeclaration[EventInput, LowerTaskOutput] {
	return factory.NewTask(
		create.StandaloneTask{
			Name: "lower",
			// 👀 Declare the event that will trigger the workflow
			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,
	)
}

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

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.

examples/python/events/event.py

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

examples/typescript/on_event/event.ts

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

examples/go/run/event.go

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

Event Filtering

Events can also be filtered in Hatchet, which allows you to push events to Hatchet and only trigger task runs from them in certain cases.

Basic Usage

You can create event filters by using the filters clients on the SDKs:

examples/python/events/filter.py

hatchet.filters.create(
    workflow_id=event_workflow.id,
    expression="input.should_skip == false",
    scope="foobarbaz",
    payload={
        "main_character": "Anna",
        "supporting_character": "Stiva",
        "location": "Moscow",
    },
)

examples/typescript/on_event/filter.ts

hatchet.filters.create({
  workflowId: lower.id,
  expression: 'input.ShouldSkip == false',
  scope: 'foobarbaz',
  payload: {
    main_character: 'Anna',
    supporting_character: 'Stiva',
    location: 'Moscow',
  },
});

examples/go/run/event.go

	payload := map[string]interface{}{
		"main_character":       "Anna",
		"supporting_character": "Stiva",
		"location":             "Moscow",
	}

	_, err = hatchet.Filters().Create(
		context.Background(),
		rest.V1CreateFilterRequest{
			WorkflowId: uuid.New(),
			Expression: "input.shouldSkip == false",
			Scope:      "foobarbaz",
			Payload:    &payload,
		},
	)

⚠️

Note the scope argument to the filter. When you create a filter, it must be given a scope which will be used by Hatchet internally to look it up. When you push events that you want filtered, you must provide a scope with those events that matches the scope sent with the filter. If you do not, the filter will not apply.

Then, push an event that uses the filter to determine whether or not to run. For instance, this run will be skipped, since the payload does not match the expression:

examples/python/events/filter.py

hatchet.event.push(
    event_key=EVENT_KEY,
    payload={
        "should_skip": True,
    },
    options=PushEventOptions(
        scope="foobarbaz",
    ),
)

examples/typescript/on_event/filter.ts

hatchet.events.push(
  SIMPLE_EVENT,
  {
    Message: 'hello',
    ShouldSkip: true,
  },
  {
    scope: 'foobarbaz',
  }
);

examples/go/run/event.go

	skipPayload := map[string]interface{}{
		"shouldSkip": true,
	}
	skipScope := "foobarbaz"
	err = hatchet.Events().Push(
		context.Background(),
		"simple-event:create",
		skipPayload,
		client.WithFilterScope(&skipScope),
	)

But this one will be triggered since the payload does match the expression:

examples/python/events/filter.py

hatchet.event.push(
    event_key=EVENT_KEY,
    payload={
        "should_skip": True,
    },
    options=PushEventOptions(
        scope="foobarbaz",
    ),
)

examples/typescript/on_event/filter.ts

hatchet.events.push(
  SIMPLE_EVENT,
  {
    Message: 'hello',
    ShouldSkip: false,
  },
  {
    scope: 'foobarbaz',
  }
);

examples/go/run/event.go

	triggerPayload := map[string]interface{}{
		"shouldSkip": false,
	}
	triggerScope := "foobarbaz"
	err = hatchet.Events().Push(
		context.Background(),
		"simple-event:create",
		triggerPayload,
		client.WithFilterScope(&triggerScope),
	)

In Hatchet, filters are “positive”, meaning that we look for matches to the filter to determine which tasks to trigger.

Advanced Usage

In addition to referencing input in the expression (which corresponds to the event payload), you can also reference the following fields:

payload corresponds to the filter payload (which was part of the request when the filter was created).
additional_metadata allows for filtering based on additional_metadata sent with the event.
event_key allows for filtering based on the key of the event, such as user:created.

Cron Trigger Bulk Run Many

We use cookies

Run on Event

Declaring Event Triggers

Pushing an Event

Event Filtering

Basic Usage

Advanced Usage