Retry policy

When Zorio pushes a webhook to your receiver and the delivery fails (timeout / non-2xx / network error), the platform retries automatically on an escalating schedule.

Definition of a failure

A receiver is considered failed when:

• It times out after 5 seconds without a response.
• It returns an HTTP status that is not 2xx (e.g. 500, 502, 503, 4xx).
• A connection error (DNS failure, TLS handshake failure, ...).

Receiver takes a while to process?

Return HTTP 200 as soon as you've verified the HMAC, then process the event asynchronously through your internal queue. Don't run business logic synchronously with Zorio — you'll pile up retries.

Retry schedule

Attempt	Delay since previous	Cumulative
1 (first try)	—	0s
2	30 seconds	30s
3	5 minutes	5m 30s
4 (last try)	30 minutes	35m 30s

After attempt 4 fails → the event moves to deadletter in the audit log.

Deadletter

When an event lands in deadletter:

• It's kept in the webhook delivery log for 30 days.
• Admins can open Admin Console → Webhook deliveries to inspect: payload, failure reason, receiver's response.
• It is NOT retried automatically after deadletter — you must fix the receiver bug, then:
  • Either click Replay on each delivery to resend it.
  • Or re-register the webhook so new events flow again.

Idempotency on the receiver side

Because Zorio may retry, the receiver MUST be idempotent — processing the same event multiple times must not cause inconsistent side effects (e.g. don't create two rows with the same UUID, don't deduct money twice).

Implementation

Every delivery carries X-Zorio-Delivery: <UUID>. Save the UUID in Redis with 24h TTL:

const seen = await redis.set(`zorio:delivery:${deliveryId}`, '1',
                              'NX', 'EX', 86400);
if (seen === null) {
  // Already processed → return 200 and skip
  return res.status(200).send('Duplicate');
}
// Process the event...

Result: no matter how many times Zorio retries, your business logic only runs once.

Throughput & concurrency

• Zorio delivers events in parallel up to 20 concurrent connections per receiver URL.
• During a burst (e.g. importing 10,000 leads), the receiver may see ~200-500 req/s. Plan capacity accordingly.
• If your receiver can't keep up → return HTTP 503 with the header Retry-After: <seconds>. Zorio honors this header (the next retry waits at least the time you specified).

When a webhook auto-suspends

If a webhook URL fails 50 events in a row without a single success → the platform auto-suspends it to stop wasting resources.

• Admins get a notification in the Admin Console.
• You must re-enable it manually after fixing the receiver.

Related docs

• Register a webhook
• HMAC-SHA256 signing
• Sample receivers