Delivery and retries
Understand acknowledgements, retryable failures, duplicates, and manual replay.
Return 2xx only after durable acceptance. A timeout can cause another delivery
even when the receiver accepted the first one. Process work asynchronously and idempotently.
Response handling
The current worker classifies responses as follows:
| Result | Behaviour |
|---|---|
2xx | Delivered |
408, 429, 5xx | Retryable while attempts remain |
Other 4xx | Non-retryable; inspect and fix the receiver |
410 | Terminal failure; destination is disabled |
| Connection, DNS, TLS, or timeout error | Retryable while attempts remain |
| Redirect | Current client follows redirects; configure the final HTTPS URL anyway |
For temporary storage failures, return 503. Returning 400 does not request a retry.
Reserve 400 for malformed or unauthenticated payloads.
Timing and attempt limits
Each delivery gets up to 8 attempts, each with a 30-second HTTP timeout. After a retryable failure, the next attempt is scheduled 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours, 12 hours and then 24 hours later, so the eighth attempt comes about 45 hours after the first.
These are the configured intervals, not a delivery SLA. Queue load, the circuit breaker and deployments can delay an attempt. Inspect each delivery's attempt count and next retry time rather than assuming a fixed time.
Duplicates and ordering
Deduplicate using the stable event ID and trusted merchant context. The transport
Idempotency-Key includes the attempt number and changes between retries; it is not
a stable event deduplication key. Multiple endpoints can receive the same event.
Do not rely on delivery order, even within one resource. Reconcile current state and choose one fulfilment owner for related events. Use a business idempotency key.
Inspect and replay
Open Settings → Webhooks → Deliveries in the matching dashboard environment. Inspect destination, status, attempts, timing, and available response/error details. Fix the receiver before using retry or replay.
Replay can repeat real side effects in your application. Confirm merchant, destination, and event. Do not bypass deduplication to make a replay appear successful. A green delivery status proves acknowledgement, not successful business processing.
Monitor failures
Alert through application monitoring on rejected signatures, failed inbox writes,
failed processing, and sustained delivery failures. Inspect delivery history as evidence.
Do not depend on endpoint.delivery.failed: it is not in the current public OpenAPI
webhook contract.
Continue with troubleshooting.
Owner: david · Reviewed 11 Oct 2026