Delivery, retries and idempotency
Answer quickly with 2xx
Section titled “Answer quickly with 2xx”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.
Retries
Section titled “Retries”| Your answer | What AD80 does |
|---|---|
2xx | Delivered. |
408, 425, 429, any 5xx, a timeout or a network error | Retried 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.
Verification handshake
Section titled “Verification handshake”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.
Secret rotation
Section titled “Secret rotation”A subscription has at most two active signing secrets. To change the secret without missing a delivery:
- Call
POST /v1/notifications/subscriptions/{id}/rotate-secret. Store the new secret from the response (it is shown once). - From now on, every request is signed with both secrets:
X-AD80-Signaturehas twov1=entries. - Deploy your receiver with the new secret (accepting either secret is fine during the switch).
- 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.
Destination rules
Section titled “Destination rules”- Only
httpsURLs. - 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.