Webhooks

A webhook subscribes an HTTPS endpoint to your organization’s run endings. When a run ends, the endpoint gets one POST with the event, signed per the Standard Webhooks specification. Fetch the run’s results with Get Run when it arrives. Only an admin or owner of the organization manages its webhooks. An organization holds at most 50.

Events

Event	When
`run.completed`	A run ended `processed`. Its results are ready, and the reports of its `report_generator` nodes have finished.
`run.failed`	A run ended `error`: it failed, could not be queued, kept crashing its workers, or went two hours without progress.
`run.cancelled`	A run ended `cancelled`: the organization had too few credits when a worker picked it up.
`webhook.ping`	You called Ping Webhook. Sent whatever events the webhook subscribes to.

Payload

{
  "type": "run.completed",
  "timestamp": "2026-07-01T12:02:30.123456+00:00",
  "data": {
    "run_id": "069dcc2c-e14c-7606-8000-2ee4fb17b4f9",
    "document_packet_id": "069dcc2c-e14c-7606-8000-2ee4fb17b4e1",
    "workflow_id": "0686bb97-8c30-70f0-8000-97669e000eb8",
    "status": "processed"
  }
}

Field	Description
`type`	The event.
`timestamp`	When the run ended (ISO 8601).
`data.run_id`	The run. Pass it to Get Run.
`data.document_packet_id`	The document packet the run executed on.
`data.workflow_id`	The workflow the run belongs to.
`data.status`	The run’s terminal status: `processed`, `error` or `cancelled`.

A webhook.ping carries data.webhook_id instead.

Verifying a delivery

Each delivery carries three headers:

Header	Description
`webhook-id`	The message id. Every retry of a message sends the same one: use it to process each event once.
`webhook-timestamp`	When this attempt was sent, in Unix seconds. Reject one too far from your clock to stop replays.
`webhook-signature`	`v1,` and the base64 HMAC-SHA256 of `{webhook-id}.{webhook-timestamp}.{body}`, keyed by your secret.

The key is the base64-decoded part of your secret after whsec_. The Standard Webhooks libraries verify all of it for you:

from standardwebhooks.webhooks import Webhook

payload = Webhook(secret).verify(raw_body, request_headers)

Verify the raw body exactly as received, before any JSON parsing.

Retries

An attempt counts as delivered when the endpoint answers 2xx within 5 seconds. A timeout, a connection failure, or a 408, 429 or 5xx answer is retried up to 5 times, with exponential backoff from about 5 minutes up to one hour between attempts. Any other answer, 4xx or a redirect, is final: redirects are never followed. A delivery that exhausts its retries is dropped. To catch up after an outage, list your workflows’ runs and handle any that ended since your endpoint last answered.

Pausing a webhook

Delete it, and create it again later. A deleted webhook gets nothing more, retries of earlier events included.

Overview

Workflows

Upload

Document packets

Runs

Corrections

Splits

Parse

Knowledge

Evals

Optimizations

SDKs and tools

API v2 (retired)

Webhooks

Events

Payload

Verifying a delivery

Retries

Pausing a webhook

​Events

​Payload

​Verifying a delivery

​Retries

​Pausing a webhook

Events

Payload

Verifying a delivery

Retries

Pausing a webhook