Skip to main content

Retry policy

What's confirmed​

Every webhook delivery attempt is recorded as a WebhookEvent with a status of pending, sent, or failed:

  • sent. Zentake's POST to your target_url received a 2xx response.
  • failed. The request errored (connection failure, timeout, or a non-2xx response), or building the payload/signature failed before the request was even sent.

Each event's status_code and response_body (truncated) record what your endpoint returned, and error records the failure reason if the request itself couldn't complete. You can inspect these via Retrieve a list of webhook events, filtering by status=failed to find deliveries your endpoint rejected.

The outgoing request itself uses a fixed 10-second timeout per attempt.

Retries: single attempt, no automatic retry​

Each WebhookEvent is delivered with a single send attempt. There is no automatic retry and no backoff schedule — if that one attempt fails (connection error, timeout, or a non-2xx response), the event is marked failed and stays failed. A failed event does not transition to sent on its own later.

Design for at-most-once delivery​

Webhook delivery is best-effort

Because there is no automatic retry, treat webhook delivery as best-effort and at-most-once — a single failed attempt means the event won't arrive at all. Design your integration so a missed or failed webhook isn't a silent data-loss risk:

  • Respond quickly with a 2xx. Do the minimum work synchronously (validate the signature, enqueue the event) and process the payload asynchronously, so slow downstream processing on your end doesn't turn into a timed-out delivery attempt.
  • Make your handler idempotent. Deduplicate by the payload's top-level id in case the same event is ever delivered more than once.
  • Reconcile with polling as a safety net. Periodically call Get responses (filtered by submitted_after) or check GET /v2/webhooks/events for status=failed entries, so a webhook that never arrived, or never succeeded, doesn't leave you with permanently missing data.
  • Use the test endpoint to validate your handler, not to validate retry behavior, Test a webhook configuration sends one simulated event and doesn't exercise any retry path.