Waits and signals
Some automations have to stop and wait for the outside world: a person approves
a refund, a warehouse confirms a pick, a carrier calls back. A Wait for event
step (wait.event) parks the run until your system sends it a signal, then
continues with whatever data the signal carried.
How a wait works
A wait.event step takes two settings:
| Setting | Meaning |
|---|---|
event | The event name the step waits for, such as approval.granted |
timeout | How long to wait: a number and a unit of ms, s, m, h, or d. Defaults to 24h. At most 30d: a flow with a longer wait cannot be published |
When a run reaches the step:
- The step is marked waiting and the run's status becomes
waiting. The run's timeline records the event it is waiting for and the timeout. - A signal with the same event name resumes it. The step succeeds, and the
signal's payload becomes the step's output, readable by later steps as
{{ steps.<key>.output }}. - The run continues with the next step.
Signals are not queued ahead of time. A signal sent before the run reaches the wait step, sent to a run that is not waiting, or carrying a different event name is not delivered, and the API tells you so.
Wait steps are not billable, and a dry run skips them.
Timeouts
If the timeout passes before a matching signal arrives, the step fails with
Timed out waiting for <event>, the run fails, and an exception opens. The
step's on_error setting does not apply to a timeout: the run always fails, so
an expired wait never goes unnoticed.
Retrying that exception re-enters the wait step with a fresh timeout, which is useful when the other system was down and is now ready to send its signal. Cancelling a waiting run stops it immediately.
The callback pattern
The usual way to use a wait is to tell another system which run to resume, then
wait for it to call back. The current run's ID is available to every step as
{{ run.id }} (see the reference language):
{
"schema_version": 1,
"steps": [
{
"key": "request_approval",
"type": "http.request",
"config": {
"url": "https://approvals.example.com/requests",
"method": "POST",
"body": {
"run_id": "{{ run.id }}",
"order_id": "{{ trigger.payload.order_id }}",
"amount": "{{ trigger.payload.total }}"
}
}
},
{
"key": "wait_approval",
"type": "wait.event",
"config": { "event": "approval.granted", "timeout": "48h" }
},
{
"key": "buy_label",
"type": "orderly.label.purchase",
"config": { "order_id": "{{ trigger.payload.order_id }}" },
"when": {
"conditions": [
{ "field": "steps.wait_approval.output.approved", "operator": "equals", "value": true }
]
}
}
]
}
The http.request step is signed with the flow's HTTP signing secret, so the
approval service can check that the request really came from your flow. The
request carries two headers:
X-Orderly-Signature: t=<timestamp>,v1=<signature>, where<timestamp>is in milliseconds and<signature>is the hex HMAC-SHA256 of<timestamp>.<body>using the signing secret.X-Orderly-Delivery: <run id>:<step key>, which identifies the request.
When the decision is made, the approval service signals the run:
curl -X POST https://api.orderly-hub.com/api/v1/flows/runs/$RUN_ID/signal \
-H "Authorization: Bearer $ORDERLY_API_KEY" \
-H "X-Organization-Id: $ORG_ID" \
-H "Content-Type: application/json" \
-d '{
"event": "approval.granted",
"payload": { "approved": true, "approver": "jane@example.com" }
}'
{ "data": { "delivered": true } }
The run resumes, steps.wait_approval.output.approved is true, and the label
is purchased.
The signal endpoint
/api/v1/flows/runs/{runId}/signalflows:run| Field | Type | Description |
|---|---|---|
event | string | Required. The event name, 1 to 200 characters. Must match the waiting step's event exactly |
payload | any JSON | Optional. Becomes the wait step's output; null when omitted |
Authenticate with an API key (oh_...) that carries the flows:run scope, or a
signed-in user with the flows.run permission. The run must belong to your
organization; any other run ID returns 404. Endpoint keys (fe_...) cannot
send signals.
The response is always 200 for a run you can see. delivered is true when
the run was waiting on that event and has resumed, and false when it was not
waiting or was waiting on a different event. A false result changes nothing,
so it is safe to send a signal again if you are unsure whether the first one
arrived.
Send a signal from the dashboard
You can resume a waiting run by hand, for example while testing. Open the run and click Send signal. The Event field is filled in with the event the run is waiting for; add an optional JSON Payload and send it. See Runs and exceptions.