Retries and redelivery

The retry schedule, when a delivery is held instead of retried, how endpoint health changes, and how to resend deliveries by hand or in bulk.

A delivery succeeds when your endpoint answers any 2xx status within 10 seconds. Anything else, including a timeout, a refused connection or a redirect, is a failed attempt. What happens next depends on the answer.

The default schedule#

After a failed attempt the delivery returns to pending with a next_attempt_at. The waits after each failure are 30 seconds, 2 minutes, 10 minutes, 30 minutes, 1 hour, 2 hours, 4 hours and 8 hours; from then on, every 12 hours. Each wait gets up to 10% random jitter so that retries from many deliveries do not arrive together. A delivery stops as failed after 15 attempts or once it is 72 hours old, whichever comes first. The 72-hour limit is a server setting that the operator of your installation can change; the schedule and the 15 attempts are fixed.

Which answers are retried#

Your answer What happens
2xx succeeded.
5xx, 408, 425, 429, timeout or connection error Retried on the schedule above.
Any other 4xx Sent twice in total, then held as paused until you act.
410 Gone The endpoint is paused automatically and its queued deliveries are held.

A held delivery is never dropped while it waits, but it still turns failed when it reaches the maximum age.

Endpoint health#

Each endpoint carries a health field. It moves to degraded after three consecutive failed attempts, to failing once attempts have failed for 24 hours, and to paused_automatically after 72 hours of failures. Pausing it yourself sets paused_by_owner. Each change caused by a delivery attempt is written to the audit trail as developer.webhook.health_changed; pausing or resuming by hand is recorded as developer.webhook.updated or developer.webhook.resumed. One successful attempt resets the count to zero.

Deliveries about the same record stay in order: while an earlier event about an invoice is undelivered, a later one about that invoice waits behind it.

Resend one delivery#

bash
curl -sS -X POST "$BUSINESS_API/developer/deliveries/dlv_2kP8aQ5mZr1NcV7xT3bLwE9fGyU/retry" \
  -H "Authorization: Bearer $API_KEY"

The 202 response shows the delivery due again with a fresh attempt budget:

json
{
  "id": "dlv_2kP8aQ5mZr1NcV7xT3bLwE9fGyU",
  "tenant_id": "ten_2jR5wQ8nLm3KxT9vB6cYpZ1dHgF",
  "webhook_id": "whk_2kP7vR3nXq9LmT4bW8cYzF1dHsJ",
  "url": "https://erp.example.test/hooks/billing",
  "event_id": "wev_2kP9bR7nWu2JfT5xQ1mKhB8cVzD",
  "event_type": "invoice.paid",
  "status": "pending",
  "attempts": 15,
  "max_attempts": 30,
  "next_attempt_at": "2026-11-19T10:31:05.204118Z",
  "response_status": 503,
  "duration_ms": 412,
  "created_at": "2026-11-16T10:12:44.930551Z",
  "sequence": 4
}

It answers 409 while the delivery is being attempted, or when its webhook was deleted. In the dashboard the same action is Resend on the delivery page.

Resend in bulk#

POST $BUSINESS_API/developer/webhooks/{id}/redeliveries puts an endpoint's failed and paused deliveries back in the queue for a window of at most 7 days (from and to, RFC 3339). You can narrow it with types and statuses (which also accepts cancelled). Send "dry_run": true first: the 200 response gives the count in requeued and changes nothing. The real call answers 201 with a wrd_ identifier. The dashboard offers this as Resend failed on the webhook page.

Retries, resends and bulk redeliveries reuse the same delivery, so webhook-id stays the same every time.

Next steps#