Guides

Source events

Source events are Mobius's durable reaction inbox. They record something that happened outside or inside a run, then a background processor decides whether the event should trigger an automation, resume a wait_for_event step, or stay internal.

The public contract is the { event, meta } envelope, not the raw database row.

Core flow

flowchart LR
  A["Provider, table, HTTP trigger, email, session, artifact, signal, or run lifecycle"]
  B[("source_events")]
  C["SourceEventProcessor"]
  D["EventDescriptor registry"]
  E["Trigger matching"]
  F["Wait delivery"]
  G["Run start or resume"]
  A --> B
  B --> C
  C --> D
  D --> E
  D --> F
  E --> G
  F --> G

Envelope

event:
  # kind-specific public payload
meta:
  id:              # source event ID
  event_type:      # e.g. table.row.inserted
  source_kind:     # e.g. table_row, integration, automation_run
  source_id:       # canonical source row ID when one exists
  provider:        # integration events only
  integration_id:  # integration events only
  occurred_at:     # upstream event time when known
  received_at:     # time Mobius received or created the event

Kind-specific stable fields are hoisted into meta so triggers and waits can filter without parsing provider payloads.

Public families

Family	Event types
Table rows	`table.row.inserted`, `table.row.updated`, `table.row.deleted`
Email	`email.received`
HTTP triggers	`http_trigger.received`
Runs	`run.completed`, `run.failed`, `run.cancelled`
Interactions	`interaction.resolved`
Signals	`signal.<name>`
Sessions	`session.message.created`
Artifacts	`artifact.created`
Integrations	Provider events such as `github.pull_request.opened`, `github.issues.opened`, `linear.issue.updated`, `jira.issue.created`, `gmail.message.received`, `slack.event`, `slack.interactivity`, and `slack.command`

Integration events are project-aware because connected providers and runtime readiness can differ by project. Inspect the catalog:

mobius catalog list-events

Triggerable vs. waitable

Some public events can start new runs. Others are wait-only because they make sense only inside an existing run.

Event	Triggerable	Waitable
`table.row.inserted`	yes	yes
`email.received`	yes	yes
`session.message.created`	yes	yes
`artifact.created`	yes	yes
Provider events	yes	yes
`interaction.resolved`	no	yes
`signal.<name>`	no	yes

The catalog response includes the current readiness and triggerability metadata for each source.

Matching

Event matchers are dotted names. Exact match and subtree wildcards are supported:

github.pull_request.opened
github.pull_request.*
github.*
table.row.inserted
signal.deploy_complete

Wildcards match descendants only. github.pull_request.* matches github.pull_request.opened; it does not match github.pull_request itself.

Wait steps

Inside an automation, wait_for_event suspends a run until a matching source event arrives:

- name: wait_for_deploy
  type: wait_for_event
  event_type: signal.deploy_complete
  match:
    environment: prod

When the event arrives, the run resumes with the matched source-event ID and mapped payload available to later steps.

Debugging

Use the provider's recent events panel or integration events API when a provider trigger did not fire:

GET /v1/projects/{project}/integration-events

That tells you whether Mobius received the provider event and whether source-event processing succeeded.

Use run event streams when the source event did fire but the automation did not behave as expected.

Triggers start runs from event matchers.
Integrations provide provider event catalogs and recent event diagnostics.
Tables emit row-change events.
Agent sessions emit session message events.