هذه الصفحة غير متاحة بلغة العربية بعد، لذا تُعرض بالإنجليزية.
Retries, idempotency and the delivery log
What counts as a success, the retry schedule, auto-disable after 25 failures, and how to stay idempotent with at-least-once delivery.
- Answer any 2xx within 10 seconds. Anything else — a timeout, a 4xx, a 5xx, or a redirect (redirects are not followed) — is a failure.
- Failed deliveries are retried after 1 m, 5 m, 30 m, 2 h, 12 h and 24 h, then marked FAILED.
- 25 consecutive failures switch the endpoint off and put a to-do on the dashboard.
- Deliveries are kept 30 days. The log with payloads and Retry buttons is at
/admin/integrations/deliveries; from code useGET /api/v1/deliveriesandGET /api/v1/deliveries/{id}(scopewebhooks:read).
At-least-once: deduplicate on the delivery id
A retry can arrive after your first attempt succeeded but timed out on the way back. Record the delivery id and skip ids you have already processed.
const seen = new Set<string>(); // use a database table with a unique index in production
export async function handleDelivery(delivery: { id: string; event: string; data: Record<string, unknown> }) {
if (seen.has(delivery.id)) return; // already processed — still answer 2xx
seen.add(delivery.id);
if (delivery.event === "invoice.paid") {
await markPaidInCrm(String(delivery.data.number), Number(delivery.data.total)); // total in minor units
}
}
async function markPaidInCrm(number: string, totalMinor: number) {
console.log("paid", number, totalMinor / 100);
}Answer first, work later: put the delivery on a queue and return 2xx quickly, so slow work never turns into timeouts and retries.
Written from: docs/API.md, src/lib/integrations/webhooks.ts, src/lib/integrations/openapi.ts