Retries & Failures

xQR automatically retries failed webhook deliveries using exponential backoff.

Success Criteria

A delivery is considered successful when your endpoint returns any 2xx HTTP status code. All other status codes (including 3xx redirects) are treated as failures.

Retry Schedule

Failed deliveries are retried up to 5 times with increasing delays:

Attempt	Delay After Failure
1st retry	5 seconds
2nd retry	30 seconds
3rd retry	5 minutes
4th retry	30 minutes
5th retry	2 hours

After all 5 retries are exhausted, the delivery is marked as permanently failed.

Auto-Disable

If a webhook endpoint accumulates 100 consecutive failures (across all deliveries), it is automatically disabled. When this happens:

• The endpoint’s enabled field is set to false
• A disabled_at timestamp is recorded
• No further deliveries are attempted

To re-enable:

1. Fix the issue with your endpoint
2. Re-enable via the dashboard or API: PATCH /v1/webhooks/{id} with { "enabled": true }
3. The failure counter resets to 0

Tip

Monitor your webhook health in the dashboard under Developers → Webhooks. Each endpoint shows its current failure count.

Delivery Log

Every delivery attempt is logged. View delivery history via:

• Dashboard: Click a webhook endpoint → Deliveries tab
• API: GET /v1/webhooks/{id}/deliveries

Each delivery record includes:

• Event type and payload
• HTTP response status and body
• Number of attempts
• Timestamps for creation, delivery, and failure

Best Practices

1. Respond quickly — Return 200 OK as soon as you receive the payload. Process the event asynchronously.
2. Handle duplicates — Use the X-XQR-Delivery header as an idempotency key. The same delivery ID may arrive more than once during retries.
3. Monitor failures — Set up alerts for webhook endpoints approaching the 100-failure threshold.