Skip to main content

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:

SettingMeaning
eventThe event name the step waits for, such as approval.granted
timeoutHow 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:

  1. 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.
  2. 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 }}.
  3. 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​

POST/api/v1/flows/runs/{runId}/signalflows:run
FieldTypeDescription
eventstringRequired. The event name, 1 to 200 characters. Must match the waiting step's event exactly
payloadany JSONOptional. 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.