Retry Policy

Automatic Retries

When a webhook delivery fails, Owl Eyes automatically retries with exponential backoff. A delivery is considered failed if:

• Your endpoint returns a non-2xx status code
• The request times out (30 second timeout)
• A connection error occurs
• SSL/TLS verification fails

Retry Schedule

Webhooks are retried with increasing delays using exponential backoff:

After 8 failed attempts over approximately 41.5 hours, the webhook is marked as permanently failed and no further retries are attempted.

Handling Duplicates

Due to retries and network issues, your endpoint may receive the same event multiple times. Use the event id field to detect and handle duplicates:

For production, use a database or Redis to persist processed event IDs:

Idempotent Handlers

Design your webhook handlers to be idempotent—processing the same event multiple times should have the same result as processing it once:

Response Requirements

Your endpoint must respond within 30 seconds with a 2xx status code. For async processing, acknowledge immediately and process later:

Manual Retry

You can manually retry failed webhooks from the dashboard or via API:

Monitoring Deliveries

View webhook delivery logs and status in your dashboard or via API:

Disabling an Endpoint

If an endpoint consistently fails, it will be automatically disabled after multiple consecutive failures. You'll receive an email notification. Re-enable it from the dashboard after fixing the issue:

Best Practices

1. Always return 2xx quickly

   Acknowledge receipt immediately and process asynchronously.

2. Handle duplicates

   Use event IDs to detect and skip duplicate deliveries.

3. Make handlers idempotent

   Processing an event twice should have the same result as processing once.

4. Monitor delivery logs

   Regularly check for failed deliveries and investigate issues.

5. Set up alerting

   Configure alerts for repeated failures or disabled endpoints.