Delivery & Retry
What counts as a successful delivery, when Tonder retries, and how to avoid duplicates.
Tonder's webhook system is designed for reliability. If your endpoint is temporarily unavailable, we automatically retry the delivery.
How delivery works
A transaction status change or event occurs.
Tonder sends a POST request to your endpoint.
Your endpoint's response determines the next step.
Based on the response, the event is marked complete or scheduled for retry.
Retry policy
| Setting | Value | Description |
|---|---|---|
| Max retry attempts | 3 | We try to deliver the 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. |
| Total retry window | ~3 minutes | The maximum time spent retrying a single event. |
Success and failure criteria
A delivery is successful if your endpoint responds with a 2xx code within 30 seconds. Any other
response is a failure and a retry is scheduled. Scenarios that trigger retries:
4xxerrors (400, 401, 404, etc.) — client errors.5xxerrors (500, 502, 503, etc.) — endpoint errors.- Timeouts when no response is received after 30 seconds.
Dead Letter Queue (DLQ)
After 3 failed attempts, the event is moved to a Dead Letter Queue for manual inspection. Failed events are stored for 30 days, accessible through the dashboard or via support, and can be retried manually after fixing the endpoint.
Implementation considerations
- Acknowledge receipt immediately with a
200 OKto prevent timeouts. - Use
metadata.external_idto deduplicate and avoid processing the same event twice. - Keep detailed logs of every webhook for debugging.
- Ensure a malformed payload or a processing error doesn't crash your system.
- Dedupe on
metadata.external_id(works across Short + Long formats). - Keep an
idempotency_keyindex in your DB. - Treat duplicate Pending + Success in Hybrid mode as intentional.
- Always verify final status via
GET /api/v1/transactions/{id}/. - Handle
Declinedfor withdrawals as a terminal state.