Tesouro delivers webhook events via HTTP POST to your registered endpoint.
Retry behavior
If your endpoint returns a 5xx status or doesn’t respond, Tesouro retries using exponential backoff within a 12-hour window. Once the window closes, the event is permanently marked as failed.
Deliveries that fail with a 4xx status are not retried. This includes errors from an inactive
or deleted subscription. Fix the underlying issue and resubmit if needed.
Retry schedule
| Attempt | Delay from previous | Cumulative time |
|---|
| 1 | 1 minute | ~1 min |
| 2 | 5 minutes | ~6 min |
| 3 | 15 minutes | ~21 min |
| 4 | 30 minutes | ~51 min |
| 5 | 1 hour | ~1h 51m |
| 6 | 2 hours | ~3h 51m |
| 7+ | 2 hours | Continues at 2-hour intervals (capped) |
Best practices
- Respond quickly: Return
2xx immediately and process the payload asynchronously. Long-running handlers risk timeouts, which trigger unnecessary retries.
- Implement idempotency: Tesouro delivers at least once. Retries may send the same event more than once. Use a stable event identifier from the payload to detect and discard duplicates.
- Log deliveries: Record incoming webhook requests. Logs are essential for diagnosing failed or out-of-order deliveries.
- Order events correctly: Due to network latency and retries, events may arrive out of chronological order. Use the attributes.updatedTimestamp field to correctly sequence events.
- Verify signatures: Where applicable verify webhook signatures before processing events.
