How Webhook Delivery Works
The webhook delivery follows these sequential steps from event creation to final resolution:1
Event Triggered
A transaction status change or event occurs
2
Immediate Delivery
Tonder sends a POST request to your webhook endpoint
3
Response Evaluation
Your endpoint’s response determines next steps
4
Success or Retry
Based on the response, the event is marked complete or scheduled for retry
Retry Policy and Configuration
When a webhook delivery fails, Tonder automatically retries according to a predefined policy:| Setting | Value | Description |
|---|---|---|
| Max Retry Attempts | 3 | We will try to deliver a webhook up to 3 times |
| Processing Timeout | 30 seconds per attempt | Your endpoint must respond within 30 seconds |
| Retry Interval | 60 seconds | We wait 60 seconds before retrying a failed attempt |
| Total Retry Window | ~3 minutes | The maximum time spent retrying a single event |
Success and Failure Criteria
A delivery is considered successful if your endpoint responds with a2xx HTTP status code within 30 seconds. Any other response is considered a failure, and a retry will be scheduled.
Common Failure Scenarios
Based on the original webhook system, these are the failure scenarios that trigger retries:4xxerrors (400, 401, 404, etc.) - Client errors indicating request problems.5xxerrors (500, 502, 503, etc.) - Server errors indicating endpoint issues.- Timeouts when no response is received after 30 seconds.
Dead Letter Queue (DLQ)
The Dead Letter Queue stores failed webhook events that couldn’t be delivered after all retry attempts:- Failed events are stored for manual inspection and potential reprocessing.
- Access is available through the Tonder dashboard or support team.
- Events can be manually retried after fixing endpoint issues.
Implementation Considerations
Key practices mentioned in the original webhook documentation:- Acknowledge receipt immediately with a
200 OKstatus to prevent timeouts. - Use the
event_idto deduplicate events and prevent processing the same event twice. - Keep detailed logs of all incoming webhook events for debugging purposes.
- Ensure that malformed payloads or processing errors don’t crash your system.
Next Steps
After understanding delivery and retry logic:- Review webhook best practices for optimal implementation patterns.
- Troubleshoot webhook issues using the setup and management guide.
- Check out HTTP response codes for proper error handling and debugging.