Skip to main content
An EventSource is a named inbound event channel. External systems dispatch events to a source by name, and the source routes them to one or more jobs or workflows via subscriptions. Each subscription can optionally filter on the event payload, so a single source can fan out to multiple targets selectively.

​
Event Sources vs Event Triggers

Event Sources and Event Triggers serve different purposes:
  • Event Sources are inbound channels for receiving external events and routing them to jobs or workflows. They are always-on endpoints that evaluate subscriptions on every dispatch.
  • Event Triggers are durable waits used by workflow steps and runs to pause execution until a matching event arrives. They are created by in-flight runs and consumed once.
Event Sources push events into the system. Event Triggers wait for events from within the system.

​
EventSource Model

The EventSource struct (defined in apps/strait/internal/domain/types.go) contains the following fields:

​
EventSubscription Model

An EventSubscription binds an event source to a target (a job or workflow). When an event is dispatched to the source, each enabled subscription is evaluated and, if matched, triggers its target.

​
Subscriptions

A subscription connects a source to a target. Two target types are supported:
  • job — When matched, a new job run is enqueued with triggered_by: "event" and the dispatched payload.
  • workflow — When matched, a new workflow run is triggered with the dispatched payload.
A single event source can have multiple subscriptions, each pointing to a different target and each with its own filter expression. This allows one inbound event to fan out to several jobs and workflows simultaneously.

​
Filter Expressions

The optional filter_expr field on a subscription controls whether a dispatched event triggers that subscription. When present, the expression is evaluated against the event payload using eventfilter.Eval:
  • If the expression evaluates to true, the subscription fires.
  • If it evaluates to false, the subscription is skipped for that event.
  • If filter_expr is omitted, the subscription fires on every dispatch.
Use filter expressions to route different event shapes through a single source. For example, a webhooks source could route "action": "created" events to one job and "action": "deleted" events to another.

​
Event Dispatch

The POST /v1/events/dispatch endpoint is the primary entry point for sending events into the system. The dispatch flow works as follows:
  1. The source is looked up by name from the request body.
  2. If the source is disabled, the dispatch is rejected.
  3. Each subscription on the source is evaluated:
    • The filter_expr (if present) is evaluated against the event payload.
    • Matching subscriptions trigger their target (enqueue a job run or start a workflow run).
  4. The response includes the number of subscriptions that fired:
A disabled event source rejects all dispatches. Subscriptions with enabled: false are also skipped during evaluation, even if their filter expression would match.

​
Schema Validation

The optional schema field on an event source accepts a JSON Schema definition. When set, inbound event payloads can be validated against this schema before subscriptions are evaluated. This provides a contract between event producers and the source, catching malformed payloads early.

​
CRUD Lifecycle

Event sources and their subscriptions are managed through the following API operations:
  • Event Triggers — Durable waits for events within workflow steps and runs.
  • Jobs — The unit of work that event subscriptions can target.
  • Workflows — Multi-step orchestrations that event subscriptions can target.