Delivery & retries
Exponential backoff, 5 attempts by default, and how to inspect delivery history.
A delivery is retried automatically on any non-2xx response or network error, using a fixed exponential backoff schedule (via BullMQ):
| Attempt | Delay before this attempt |
|---|---|
| 1 | immediate |
| 2 | 1 minute |
| 3 | 5 minutes |
| 4 | 30 minutes |
| 5 | 2 hours |
| 6 | 12 hours |
maxRetries (default 5, configurable 1–10 at endpoint creation) caps the additional
attempts after the first — once exhausted, the delivery is marked failed and VUZ stops
trying.
A POST /webhooks/{id}/test delivery is not retried (maxAttempts: 1) — it's meant
for an immediate connectivity check, not production reliability testing.
Respond fast, respond 2xx
- Return a
2xxstatus as soon as you've durably queued the event for processing — don't do slow work (calling other APIs, heavy DB writes) inline before responding. VUZ's request timeout is 30 seconds. - Any non-2xx status (including
3xx,4xx,5xx) is treated as a failure and retried on the schedule above. - Deliveries are at-least-once, not exactly-once — design your handler to be
idempotent on
X-Vuz-Delivery-Id(dedupe on that ID if you can't tolerate reprocessing).
Inspecting delivery history
Delivery history and manual retry are dashboard/JWT-only today (not exposed to API keys or
OAuth tokens): GET /webhooks/{id}/deliveries and
POST /webhooks/{id}/deliveries/{deliveryId}/retry. If a delivery is stuck failing, check
those from your VUZ dashboard, or reach out to developers@vuz.co.il.
Disabling an endpoint
PATCH /webhooks/{id} with { "isActive": false } stops new deliveries without deleting
the endpoint (or its secret) — useful for a temporary pause during maintenance.