Webhook Retries and Delivery Guarantees

Webhooks are delivered with an at-least-once model. Your endpoint must be idempotent and resilient to duplicate events and out-of-order arrival.

Delivery Behavior

  • Success is any 2xx response from your endpoint.
  • Non-2xx responses trigger retry with exponential backoff.
  • Retries stop after max attempts or delivery window expiry.
  • Event ordering is best effort; reconcile by event timestamp and resource status.
Recommended webhook consumer pattern
// 1) Verify signature
// 2) De-duplicate by event id
// 3) Process idempotently
// 4) Return 200 quickly

if (alreadyProcessed(event.id)) {
  return res.status(200).json({ received: true, duplicate: true });
}

processEvent(event);
markProcessed(event.id);
return res.status(200).json({ received: true });
Example delivery headers
X-Tinker-Event-Id: evt_123
X-Tinker-Delivery-Id: del_987
X-Tinker-Retry-Attempt: 2
X-Tinker-Signature: sha256=<hex>