Callbacks

Receive run results via HTTP webhook. Signing, retries, redelivery.

Long-running models push their final payload to a URL you control. You provide the URL on the request; Runflow POSTs the result when the run finishes.

Pattern

1. Call POST /v1/models/{model_id}/runs with callback_url, where {model_id} is the slash-delimited provider/model path shown on the model page.
2. Save the returned id. Callback payloads call the same value run_id.
3. Run finishes in the background.
4. Runflow POSTs to callback_url.
5. Your handler returns 200 OK within a few seconds.

Callback payload

The callback body is an event envelope, frozen at delivery time:

{
  "event": "run.completed",
  "run_id": "01J0...",
  "status": "succeeded",
  "output": { "image_urls": ["https://..."] },
  "duration_ms": 102345,
  "created_at": "2026-05-06T10:00:00.000+00:00",
  "completed_at": "2026-05-06T10:01:42.000+00:00",
  "metadata": null
}

Field	Notes
event	One of run.completed, run.failed, run.cancelled, run.partial_succeeded. Event names use UK spelling (cancelled, two ls); the run’s status_code field uses US spelling (canceled). Both literals are stable.
run_id	UUIDv7 of the run. Match against the id from your POST /runs response.
status	Terminal callback status. Run records expose the same value as status_code on GET /v1/runs/{id}.
output	The normalized model output on success, an error envelope on failure, or null if cancelled. Batch callbacks use a self-describing {items, succeeded, failed, cancelled, total} envelope, see the OpenAPI for the full shape.
duration_ms	Total run wall-clock time.
created_at, completed_at	ISO 8601, +00:00 offset (not Z) so HMAC verification stays byte-equivalent.
metadata	Whatever you passed at run creation, verbatim.

Output URLs are presigned and time-limited. Download or re-upload them to your own storage on receipt. Batch callbacks ship the same envelope but with batch_id instead of run_id.

Verify the source

Create a callback secret and Runflow signs every callback with HMAC-SHA256:

curl -X POST https://api.runflow.io/v1/callback-secrets \
  -H "Authorization: Bearer $RUNFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"label": "production"}'

Save the returned plain_secret. Runflow then sends Runflow-Signature: <hmac-hex> on every callback (alongside a Runflow-Request-Id for log correlation). See Verify callback signatures for handler code.

Retries

Runflow retries failed callbacks (non-2xx response, timeout, connection error) on an exponential schedule. Inspect attempts with GET /v1/runs/{run_id}/callback.

Manual redelivery

Replay a callback at any time:

curl -X POST https://api.runflow.io/v1/runs/{run_id}/callback-redeliveries \
  -H "Authorization: Bearer $RUNFLOW_API_KEY"

Local development

Your laptop is not reachable from the public internet. Tunnel it:

ngrok http 3000
# use the https://abc123.ngrok-free.app URL as callback_url

Related

Verify signatures

HMAC verify in Node and Python.

Callback delivery API

History, redelivery, and secrets.