Skip to content

Signals and waits

A wait step pauses its branch until something happens: a duration passes, a time arrives, or a signal comes from one of your systems. Other branches keep going.

- id: soak
wait: { for: 30m } # a duration, at most 7 days
- id: maintenance_window
wait: { until: "2026-12-01T02:00:00Z" } # a time
- id: store_connected
wait: { signal: store_connected, timeout: 14d }
Your system
Server
Run
wait store_connectedthe step is waiting
POST …/signals/store_connected{"store_id": "st_123"}
checks the payload against the wait's outputs
step succeeded; outputs.store_id = st_123

Your system sends a signal with any token that may act on the run:

Terminal window
curl -X POST "$RUNBOOK_HOST/v1/executions/$EXE/signals/store_connected" \
-H "Authorization: Bearer $RUNBOOK_TOKEN" -H 'Content-Type: application/json' \
-d '{"store_id": "st_123"}'

A signal wait may declare outputs, in the same form as a task’s. The payload must match: an invalid payload is refused with 422 signal.invalid_payload (field errors named payload.<field>), nothing is recorded, and the step keeps waiting. A valid payload becomes the step’s outputs; fields the declaration doesn’t name are ignored. Without outputs, any payload is accepted and none is kept.

customer-onboarding.yaml
metadata: { id: customer-onboarding }
spec:
inputs:
customer: { type: string, required: true }
steps:
- id: store_connected
wait:
signal: store_connected
timeout: 14d
outputs:
store_id: { type: string, required: true }
plan: { type: enum, options: [starter, growth, enterprise] }
- id: welcome
actor: agent
instructions: >-
Send ${{ inputs.customer }} the welcome pack for the
${{ steps.store_connected.outputs.plan }} plan (store
${{ steps.store_connected.outputs.store_id }}).

wait.timeout bounds any wait; past it, the step times out and its on_failure applies. A signal wait without one is bounded by the run’s spec.execution.timeout. Waits take reminders and escalation (remind_after, escalate_after), so someone hears about a signal that never came.