Webhook delivery & retries

Retry policy

ModelRiver implements exponential backoff with the following schedule:

After 8 failed attempts, the webhook is moved to the Dead Letter Queue (DLQ) for manual inspection.

Successful delivery

Your endpoint should return a 2xx status code (preferably 200 OK) to acknowledge successful receipt. ModelRiver considers any 2xx response as successful and will not retry.

Failed delivery

Any of the following triggers a retry:

• Non-2xx status code (4xx, 5xx)
• Network timeout (30-second default)
• Connection refused or DNS resolution failure
• TLS handshake failure

Monitoring webhooks

All webhook deliveries are logged in your project's Request Logs:

• Timeline view shows each delivery attempt with timestamps
• Status indicators mark success, failure, or pending retries
• Payload inspection lets you view the exact data sent
• Callback logs (for event-driven workflows) show your backend's response

Filter logs by event_name to isolate specific event-driven workflows.

Dead letter queue

When all retry attempts are exhausted:

1. The webhook delivery is moved to the DLQ
2. The original payload is preserved for inspection
3. You can manually retry from the DLQ in the console
4. DLQ entries are retained for 30 days

Best practices

• Respond quickly: Return 200 OK immediately and process webhooks asynchronously in a background job
• Implement idempotency: Use channel_id as a deduplication key since retries may deliver the same payload multiple times
• Monitor delivery rates: Track webhook success rates in Observability to catch endpoint issues early
• Use health checks: Ensure your webhook endpoint is monitored and alerts you to downtime
• Log failures: Record non-2xx responses with details to debug integration issues

Next steps

• Standard webhooks: Payload structure reference
• Signature verification: Secure your endpoints
• Observability: Monitor webhook delivery timelines