Triggering Workflows with Events in Hatchet

Hatchet provides a powerful event-driven architecture that allows you to trigger workflows based on specific events. Events can be external, such as incoming webhooks or messages from a message queue, or internal, such as the pushed from another workflow. By leveraging event-based triggers, you can create reactive and dynamic workflows that respond to real-time data and business logic.

Configuring Event Triggers

To trigger a workflow based on an event, you need to configure the on property in the workflow definition. Here's an example of how to define an event trigger:

const myWorkflow: Workflow = {
  id: "my-workflow",
  description: "A workflow triggered by an event",
  on: {
    event: "user:created",
  },
  steps: [
    // Define your workflow steps here
  ],
};

In this example, the on property is set to an object with an event property. The event property specifies the name of the event that should trigger the workflow. When an event with the specified name is received by Hatchet, it will automatically start a new instance of the workflow.

Event Payloads

When an event triggers a workflow, Hatchet passes the event payload to the workflow as input data. The event payload can contain relevant information or context that the workflow steps can use during execution.

For example, if the event is user:created, the event payload might include details about the newly created user, such as their ID, email, or any other relevant attributes. You can access this event payload within your workflow steps using the context.workflowInput() method.

const myStep: Step = async (context: Context<UserCreatedEvent>) => {
  const eventPayload = context.workflowInput();
  const userId = eventPayload.userId;
  const userEmail = eventPayload.email;
 
  // Use the event payload data in your step logic
  // ...
};

Event Sources

Hatchet supports various event sources that can trigger workflows. Some common event sources include:

Internal Events: Hatchet allows you to generate internal events using our SDKs from within your existing APIs. For example, you can push an event when a specific user request is made.
Webhooks: Hatchet can expose webhook endpoints that listen for incoming HTTP requests. When a webhook is triggered, it generates an event that can be used to start a workflow.

Event-Driven Best Practices

When working with event-driven workflows, consider the following best practices:

Event Naming: Use clear and descriptive names for your events to make them easily understandable and maintainable. Follow a consistent naming convention across your workflows.
Event Granularity: Strike a balance between granularity and complexity when designing your events. Too many fine-grained events can lead to increased complexity, while too few events may limit the flexibility and reactivity of your workflows.
Event Validation: Implement proper event validation and error handling in your workflows. Ensure that the event payloads conform to the expected schema and handle any invalid or missing data gracefully.
Idempotency: Design your workflows to be idempotent, meaning that they can handle duplicate events without causing unintended side effects.

Events Dashboard

Hatchet provides a visual dashboard for monitoring and managing events. You can view incoming events, inspect event payloads, and configure event triggers directly from the dashboard. This makes it easy to monitor the flow of events and manage your event-driven workflows.

Streaming Cron Scheduling