Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.runflow.io/llms.txt

Use this file to discover all available pages before exploring further.

A webhook is an org-level subscription to one or more event types. Configure the URL once; Runflow delivers every matching event from any run in the organization. Use webhooks when you want a single endpoint to receive all activity instead of setting callback_url per run.

​
Webhooks vs callback_url

MechanismScopeWhere it’s setWhen to use
callback_url (per run)One runOn POST /v1/models/{model}/runsOne-off pipelines, ephemeral workers, ngrok during dev. See Callbacks.
Webhooks (org-level)All runs in the orgPOST /v1/webhooks onceProduction. Consistent endpoint, signed deliveries, retry history, redelivery.
Both deliver the same run.completed / run.failed / run.cancelled payload shape documented under Callbacks. Pick callback_url if you don’t need history; pick webhooks if you do.

​
Endpoints

MethodPathPurpose
GET/v1/webhooksList webhooks for the org.
POST/v1/webhooksCreate a webhook.
GET/v1/webhooks/{id}Fetch a webhook by id.
PATCH/v1/webhooks/{id}Update url, secret, or event subscriptions.
DELETE/v1/webhooks/{id}Delete a webhook.
GET/v1/webhooks/event-typesReference list of every event you can subscribe to.
GET/v1/webhooks/event-types/{code}Detail for one event type.
GET/v1/webhooks/{webhook_id}/deliveriesDelivery history (pass any as webhook_id to span all webhooks).
GET/v1/webhooks/{webhook_id}/deliveries/{id}One delivery, with the recorded payload.
GET/v1/webhooks/{webhook_id}/deliveries/{delivery_id}/attemptsPer-attempt records (timestamps, HTTP status, response).
GET/v1/webhooks/{webhook_id}/deliveries/{delivery_id}/attempts/{id}One attempt.
Every endpoint is Authorization: Bearer $RUNFLOW_API_KEY. The X-Organization-Id header is optional and defaults to the key’s org.

​
Create a webhook

POST /v1/webhooks takes three required fields plus an optional list of event subscriptions: 
curl -X POST https://api.runflow.io/v1/webhooks \
  -H "Authorization: Bearer $RUNFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/runflow",
    "secret_ciphertext": "<encrypted-secret>",
    "secret_fingerprint": "abcd",
    "event_subscriptions": [
      { "event_type_code": "run.completed" },
      { "event_type_code": "run.failed" }
    ]
  }'
FieldTypeRequiredNotes
urlstringyesHTTPS endpoint Runflow POSTs to. Max 2048 chars.
secret_ciphertextstringyesOrg-managed encrypted signing secret. Used to HMAC the payload.
secret_fingerprintstringyes4-char display fingerprint for the dashboard.
event_subscriptions[]arraynoOne subscription per event type. Add or remove later via PATCH.
Subscribing to zero events creates a webhook that never fires. Subscribe to at least one event type from GET /v1/webhooks/event-types.

​
Event types

GET /v1/webhooks/event-types returns every code Runflow can emit, with the schema each event carries. Common ones today:
CodeFired when
run.completedA run reached succeeded.
run.failedA run reached failed.
run.cancelledA run was cancelled (admin or auto).
run.partial_succeededBatch run finished with at least one failed item.
Event names use UK spelling (cancelled, two ls); the run’s status_code field uses US spelling (canceled). Both literals are stable.

​
Deliveries and attempts

Every event that matches a webhook produces a delivery. Each delivery has one or more attempts (retries on 5xx, timeouts, or network errors). 
# List recent deliveries for one webhook
curl https://api.runflow.io/v1/webhooks/{webhook_id}/deliveries \
  -H "Authorization: Bearer $RUNFLOW_API_KEY"

# Across every webhook in the org
curl https://api.runflow.io/v1/webhooks/any/deliveries \
  -H "Authorization: Bearer $RUNFLOW_API_KEY"

# One delivery with its attempts
curl https://api.runflow.io/v1/webhooks/{webhook_id}/deliveries/{delivery_id} \
  -H "Authorization: Bearer $RUNFLOW_API_KEY"

# Per-attempt detail (HTTP status, response_body, next_retry_at)
curl https://api.runflow.io/v1/webhooks/{webhook_id}/deliveries/{delivery_id}/attempts \
  -H "Authorization: Bearer $RUNFLOW_API_KEY"
Each attempt records status_code, response_time_ms, response_body, succeeded, and next_retry_at. Use them to debug 5xx storms or a misconfigured receiver.

​
Verify the signature

Runflow signs every webhook delivery with HMAC-SHA256 of the raw body using your webhook’s secret. The signature ships in the Runflow-Signature header alongside Runflow-Request-Id for log correlation. The verification code is the same as for per-run callbacks - see Verify callback signatures.

​
Receiver checklist

  • Return 2xx within a few seconds. Runflow treats non-2xx, timeouts, and network errors as failures and retries on an exponential backoff.
  • Verify Runflow-Signature before trusting the body.
  • Be idempotent on delivery.id and run_id. Retries can deliver the same event more than once.
  • Log Runflow-Request-Id. It is the join key against GET /v1/webhooks/{webhook_id}/deliveries.
  • Use /v1/webhooks/any/deliveries to triage when you’re not sure which webhook fired.

Callbacks (per run)

Use callback_url for one-off runs.

Verify signatures

HMAC verification in Node and Python.

Errors

Status codes and the error envelope.

API reference

Full endpoint reference.