انتقل إلى المحتوى
تجربة مجانية 14 يومًا، بلا بطاقة9 لغات176 نوع عمل · 50 تطبيقًا
AR· USD
جرّب عرضًا حيًاابدأ التجربة المجانية

هذه الصفحة غير متاحة بلغة العربية بعد، لذا تُعرض بالإنجليزية.

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.

  • about 7 min
  • 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 use GET /api/v1/deliveries and GET /api/v1/deliveries/{id} (scope webhooks: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.

Idempotent handler
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