Webhooks

Use "enabled_events": ["*"] to receive everything.

The response includes the signing secret once:

Every endpoint must be HTTPS, in live and test mode alike, and the URL is checked before it is stored: internal addresses, private ranges and this API's own host are refused. The same check runs again at delivery time, so an address that later resolves somewhere private is still blocked.

The body is the event envelope described in Events.

The delivery policy, generated from the API's own description of it:

Anyone can POST to your URL. The signature is what proves a request came from us.

The header is HMAC-SHA256 over "{timestamp}.{raw_body}", keyed with your endpoint secret:

Copy-pasteable implementations are below. They do both of those things.

Return any 2xx and we stop. Anything else is a failure and will be retried.

Deduplicate on Agentency-Event-Id. A retry re-sends the same id, and receiving one twice is normal rather than exceptional.

A delivery gets seven attempts in total: the first, then six retries over roughly seventeen and a half hours, with increasing gaps of about 1 minute, 5 minutes, 30 minutes, 2 hours, 5 hours and 10 hours. After the seventh attempt it is marked failed and left alone.

If 20 attempts in a row fail, across its deliveries, the endpoint is disabled automatically, and you get a webhook_endpoint.disabled event on your other endpoints and an email. This protects both sides from a dead URL absorbing deliveries forever. Disabling an endpoint yourself (PATCH with status: disabled) sends no event.

A disabled endpoint is sent nothing: a delivery that falls due while it is off is marked failed without a request, and turning the endpoint back on does not re-send it. Retry those deliveries one by one, or read what you missed from GET /v1/events.

There is also a circuit breaker: an endpoint that is clearly down stops receiving attempts for a couple of minutes rather than burning through its retry budget while it is unreachable.

Inspecting and replaying

Each record has its status, the attempts made, when the next one is due, and your endpoint's answer to the latest attempt: the status code, the first 512 characters of the body and how long it took. A null response_status means no answer came at all — a timeout or a refused connection. Filter with status=failed to find what to re-send:

Only a failed delivery can be retried, and retrying resets its attempt budget. It re-sends the same event, with the same id, to that endpoint only — no new event is recorded. Turn a disabled endpoint back on first, or the retry fails again without a request. A delivery currently in flight returns 409 DELIVERY_IN_FLIGHT, and one your endpoint already accepted returns 409 DELIVERY_ALREADY_DELIVERED, so neither is sent twice. Test pings and retries share a budget of 20 a minute per key.

Rotation returns a new secret and keeps the old one valid for 24 hours. During that window deliveries are signed with both, so you can deploy the new secret without dropping anything.

This only works if your verifier checks every v1 value. A verifier that looks at one signature will reject everything for 24 hours.

Rotating again inside those 24 hours keeps the original secret signing until its window ends and replaces only the new one, so finish one rotation before you start the next.

Sends a ping event through the real delivery pipeline — same signing, same headers, same retries — to this endpoint only, whether or not it subscribes to ping. The response carries the ping's event_id, so you can find its delivery. Use it to confirm a new endpoint before you rely on it.

For local development, point the endpoint at an HTTPS tunnelling service. mode is a label for your own bookkeeping: test endpoints receive the same events as live ones and need HTTPS too.

• Parsing before verifying. Sign the raw bytes.
• Keeping one v1. Breaks silently for 24 hours after every rotation.
• Not checking the timestamp. A signature with no time bound is replayable forever.
• Slow handlers. Ten seconds, then it is a retry.
• No deduplication. At-least-once delivery means you will see duplicates.
• Ignoring webhook_endpoint.disabled. That is the platform telling you it has given up on a URL.

• Events — the catalogue and payload shape.
• Going live — which events to subscribe to first.
• Security — secret handling.