Skip to content

Delivery, retries and idempotency

Your endpoint accepts a delivery by answering any 2xx status. AD80 waits at most 10 seconds for the answer, reads at most 4 KiB of your response body (shown in the delivery log) and does not follow redirects. Verify the signature, store the event, answer 2xx, and do the slow work afterwards.

Your answerWhat AD80 does
2xxDelivered.
408, 425, 429, any 5xx, a timeout or a network errorRetried later.
Any other 4xx (for example 400, 401, 404)Not retried: the delivery is marked dead.
A redirect (3xx)Not followed; treated as not accepted.

Retries wait about 30 seconds after the first failure and twice as long after each further failure (with some random spread), up to 4 hours between two attempts. A Retry-After header on your answer is honoured. After 24 hours without success the delivery is marked dead. You can send a dead delivery again from the delivery log (Redeliver) or with POST /v1/notifications/deliveries/{id}/redeliver; it then has another 24 hours.

AD80 also limits how fast it sends to one destination. A delivery over that limit is delayed, never dropped.

Idempotency: de-duplicate on the delivery id

Section titled “Idempotency: de-duplicate on the delivery id”

Delivery is at least once. A lost network answer or a crash at the wrong moment makes AD80 send the same delivery again. Every attempt of a delivery, and every redelivery, carries the same X-AD80-Delivery header (also sent as Idempotency-Key, and as id in the body).

Keep the delivery ids you have processed (for example in a table with a unique index, for a few days) and ignore a delivery whose id you have already seen. event_id identifies the underlying event if you need it.

A new webhook subscription first receives a notify.verify event (delivery id verify-<subscription id>) with a one-time code. Your endpoint should accept it with 2xx like any other event; then send the code back with POST /v1/notifications/subscriptions/{id}/confirm, or enter it on the dashboard. Until then no other event is sent.

A subscription has at most two active signing secrets. To change the secret without missing a delivery:

  1. Call POST /v1/notifications/subscriptions/{id}/rotate-secret. Store the new secret from the response (it is shown once).
  2. From now on, every request is signed with both secrets: X-AD80-Signature has two v1= entries.
  3. Deploy your receiver with the new secret (accepting either secret is fine during the switch).
  4. Call POST /v1/notifications/subscriptions/{id}/retire-secrets. Only the newest secret signs from then on.

Rotate at once if a secret may have leaked.

  • Only https URLs.
  • The URL must resolve to a public address. Private, loopback, link-local, carrier-grade NAT and cloud metadata addresses are refused. The check is repeated on every send, and AD80 connects to the address it checked.