Skip to content
hyperspool

Event catalog

The event catalog lists the event types that exist in a project, each with a sample payload, so you can wire a handler or a trigger step to a type without knowing it by heart.

Terminal window
spool event types
# run.started   system    A run began. The non-terminal member of the lifecycle set.
# …
# order.placed  observed  -

Where you see it

Section titled “Where you see it”

spool event types prints the catalog: each type, where it comes from and its description. The canvas reads the same catalog for a trigger step’s event picker. With the payload examples, it is one HTTP call with a token:

Terminal window
curl -H "Authorization: Bearer $TOKEN" \
  https://api.hyperspool.dev/api/v1/orgs/<org>/projects/<project>/events/catalog

What it lists

Section titled “What it lists”

Types from three sources:

  • System: the platform’s own, the lifecycle events below and schedule.tick, each with an example of its shape. The list also carries feedback.submitted and invite.requested, which never arrive on your projects.
  • Declared: types named by an emit step in one of the project’s stored graphs, read from its draft, or from the published version when there is no draft. A graph that emits deploy-done makes the type discoverable before it has fired. Each signed webhook adds its <webhook>.push, with the envelope’s shape (see Forge deliveries).
  • Observed: distinct types among the project’s latest 200 events on the bus, each with its last payload as the example.

Lifecycle events

Section titled “Lifecycle events”

A top-level run publishes these as it starts, waits and ends. run.* matches all seven.

Type When Adds to the payload
run.started the run began, or left a concurrency queue
run.awaiting it stopped for something outside itself, usually a person substate, waits_on, prompt, fields, signal, deadline_ms, workflow_name
run.wait_expired a bounded wait gave up and the run carried on what run.awaiting adds, except substate and deadline_ms
run.wait_withdrawn the run ended while stopped on a wait, so nobody needs it answered the same as run.wait_expired
run.succeeded it finished successfully output
run.failed it failed error
run.cancelled it was cancelled reason

Every lifecycle payload also carries run_id, status, workflow, tags, tag, trigger and run_url. Lifecycle events explains those fields, how to tell someone a run is waiting, and which runs don’t announce.

What an entry looks like

Section titled “What an entry looks like”
  • event_type: the type you subscribe to.
  • origin: system, declared or observed.
  • description: present for system and declared types.
  • payload_example: for a system type, the shape of the whole envelope; for an observed type, the payload it last carried. Absent for a type a graph declares.
{
  "event_type": "run.failed",
  "origin": "system",
  "description": "A run failed.",
  "payload_example": {
    "type": "run.failed",
    "payload": { "run_id": "…", "status": "failed", "workflow": "…", "error": "…" }
  }
}

workflow in a lifecycle payload is the workflow type, such as hyperspool/pipeline/v1.

Subscribing before it fires

Section titled “Subscribing before it fires”

A handler’s on patterns match by type, so a handler registered for a type that has never fired runs the first time the type appears. The catalog only helps you find the name and the payload shape.

See also

Section titled “See also”