# Understanding Webhook Retries

When your webhook endpoint returns a non 2XX response or is unavailable, DNSRadar automatically retries delivery with increasing delays.

Understanding this retry behavior helps you build resilient integrations.


## Retry Schedule

DNSRadar uses an exponential backoff strategy with 9 retry attempts over 24 hours:

| Attempt | Delay After Failure |
|---------|---------------------|
| 1st retry | 5 minutes |
| 2nd retry | 10 minutes |
| 3rd retry | 15 minutes |
| 4th retry | 30 minutes |
| 5th retry | 1 hour |
| 6th retry | 2 hours |
| 7th retry | 6 hours |
| 8th retry | 12 hours |
| 9th retry | 24 hours |


After the 9th failed attempt, the webhook is automatically disabled.


## What Triggers Retries

Retries are triggered when:

- HTTP status codes 300-599 (server errors)
- Network timeouts (> 5 seconds)
- Connection failures
- DNS resolution failures
- SSL/TLS errors


## Retry Behavior

### Pending Events Queue

When a webhook fails, subsequent events are queued:

```
Event 1: Fails → Queued for retry in 5 minutes
Event 2: Detected → Queued (waits for Event 1)
Event 3: Detected → Queued (waits for Event 1)
```

Once Event 1 successfully delivers, Events 2 and 3 are sent immediately.

This is to ensure that if a webhook is down, we won't try at every new Events to deliver you the payload. All the subsequent Events payload will be queued until one request succeed (either by automatic retry, or via a call to our API).


### Successful Retry

When a retry succeeds:
1. The failed event is delivered
2. All queued events are delivered
3. Retry counter resets
4. Webhook remains active


### Failed Retry

After all retries fail:
1. Webhook is automatically disabled
2. You receive a notification email
3. Queued events are not delivered
4. You must manually re-enable the webhook


## Automatic Webhook Disabling

> 🚨 **DANGER:** **Auto-Disable After 24 Hours**: Webhooks that fail all 9 retry attempts are automatically disabled. Fix the issue and manually [re-enable](/docs/enable-disable-webhooks) the webhook.


## Best Practices

* Return a correct status code, in the range 2xx
* Respond quickly. If your endpoint is doing a heavy work, run it after responding or schedule the work via a task queue


## Retry vs. Delivery Guarantees

> ℹ️ **INFO:** **At-Least-Once Delivery**: DNSRadar guarantees at-least-once delivery for successful webhooks. Events may be delivered multiple times if retries succeed after temporary failures.

DNSRadar provides:
- ✅ At-least-once delivery (events delivered one or more times)
- ✅ Ordered delivery (events delivered in occurrence order)
- ❌ Exactly-once delivery (duplicates possible during retries)

Design your endpoints to be idempotent to handle this guarantee.


## Troubleshooting

### Webhook Keeps Getting Disabled

Check:

1. Endpoint accessibility from internet
2. SSL certificate validity
3. Response time (< 30 seconds)
4. Error logs in your application
5. Rate limiting on your endpoint


### Events Not Arriving

Check:

1. Webhook is enabled (`is_active: true`)
2. No errors in [webhook request history](/docs/webhook-requests)
3. Endpoint logs show no requests
4. Firewall rules allow DNSRadar IPs


## Next Steps

- [View Webhook Request History](/docs/webhook-requests)
- [Enable/Disable Webhooks](/docs/enable-disable-webhooks)
- [Test Webhooks](/docs/test-webhooks)