poll_url. There are two ways to ask:
- Webhook endpoints. Add an address once, and it hears about every run on your account: from the Workbench, from a recipe, from an automation, and through the API. Each endpoint has its own signing secret, which you can rotate.
webhook_urlon a call. Pass it when you start one run, and only that run is sent there.
webhook_url goes to that URL and to every endpoint that hears the event.
Webhook endpoints
Manage endpoints under API & MCP keys → Webhook endpoints, or with the API. An account holds up to 10.
The answer is the endpoint, plus
secret: its whsec_ signing secret. This is the only time the secret is shown. Copy it now. If you lose it, rotate it. A retry with the same Idempotency-Key answers with the same endpoint and "secret": null.
An endpoint never shows its secret after it is made. It shows
enabled, disabled_reason when we switched it off, failing_since while its deliveries are failing, and previous_secret_expires_at while a rotated-out secret still signs.
Every change to an endpoint, and every test and replay, is on your account activity.
Managing endpoints takes a key with the admin scope. A test key can list endpoints and read the delivery log, and is refused (403 test_mode_unsupported) on everything that adds, changes, deletes, rotates, pings or replays — those reach your real receivers. Test runs are still delivered to your endpoints, marked "livemode": false.
Pass webhook_url on a call
POST /api/v1/run/{skill}, POST /api/v1/runs and POST /api/v1/convert. A webhook_url isn’t an endpoint: it has no settings, and it is signed with your account’s webhook signing secret, shown under API & MCP keys → Webhook signing secret. That secret can’t be rotated. Use an endpoint if you need to.
What arrives
One POST per run, with a JSON body:livemode is false for a run made with a test key. Test runs are delivered like any other, so you can build the receiving end without spending anything.
A recipe run sends one
run.* event. Its steps don’t send job.* events of their own.
data holds signed download links, and they expire. Fetch the files when the webhook arrives, or read poll_url again later for fresh links.
Slack, Discord and Google Chat
A Slack, Discord or Google Chat incoming-webhook URL (https://hooks.slack.com/services/…, https://discord.com/api/webhooks/…, https://chat.googleapis.com/v1/spaces/…/messages?key=…) is sent a chat message instead of the JSON above: whether the run finished or failed and why, a link to each file it made (good for 7 days), the first picture, and the automation’s page for a run an automation started. A test posts a test message. The delivery log still shows the JSON event.
Check the signature
Every POST carries a header:v1 is HMAC-SHA256 of t, a full stop, and the raw request body, keyed with the signing secret: the endpoint’s own, or your account’s for a webhook_url. Both start whsec_.
While a rotation overlaps, the header carries two v1 values, one for each secret, newest first:
- Take the raw body exactly as it arrived. Do this before any JSON parsing.
- Compute
HMAC-SHA256(secret, t + "." + body)in hex. - Compare it to every
v1in the header with a constant-time comparison. Accept the request if any one matches. - Refuse anything whose
tis more than five minutes from now. This stops a captured request from being replayed later.
Rotate a secret
Rotating gives an endpoint a new secret. The old one keeps signing beside it for an overlap, so you can deploy the new secret without refusing what arrives meanwhile.overlap_hoursis 24 if you leave it out, and can be anything from 0 to 168 (a week).0retires the old secret at once.- The answer carries the new
secret, once. - Until
previous_secret_expires_at, every delivery carries twov1signatures. A receiver holding either secret accepts it. - Rotating again during an overlap retires the oldest secret. Only two ever sign.
Test an endpoint
Send test in the app, orPOST /api/v1/webhook-endpoints/{id}/ping, sends the endpoint a ping:
event_id. Look it up in the delivery log a moment later.
Delivery log
Every attempt to send an event is logged for 30 days, retries included, each as its own row. In the app it’s under Deliveries below your endpoints: open a row to see what was sent and what came back.
Returns
{"deliveries": [...], "next": "…"}, newest first. next is null on the last page. Each delivery has:
Replay a delivery
Replay on a logged delivery, orPOST /api/v1/webhook-deliveries/{id}/replay, sends the same body again to the same address. It keeps the same id, so your de-duplication still works, and it is signed with the secrets that are live now. It is sent even to an endpoint that is switched off. The new attempt is logged with replay_of set.
Delivery
- Answer with any 2xx within 15 seconds. Anything else counts as a failed attempt, and so does a redirect. The attempt is retried with growing gaps, up to eight times. Each address is retried on its own, so one that’s down never holds up the others.
- Sent once per run, per address. A retry can arrive after a slow success you’ve already handled, and so can a replay, so key your handling on
id. - https only, never a private address and never a Mediamonster one. A
webhook_urlthat isn’t accepted is refused withbad_webhookbefore anything is charged. - To know a delivery is ours, check its signature — don’t rely on a secret in the URL. Credentials in the user part of the URL (
user:pass@) are refused, and your account activity shows an endpoint’s address without its query string.
Endpoints that keep failing
An endpoint that has failed 20 attempts in a row, over at least three days, is switched off. Itsdisabled_reason says why, and your account activity shows when. A short outage never trips this, however many retries it causes. Fix the receiver, then switch the endpoint back on: that clears the reason and starts the count again. Replay anything you missed from the delivery log.
