> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tesouro.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Delivery and retry behavior

> Understand how Tesouro delivers webhook events, retries failed deliveries, and how to handle them reliably.

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.

<Warning>
  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.
</Warning>

### 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

1. **Respond quickly**: Return `2xx` immediately and process the payload asynchronously. Long-running handlers risk timeouts, which trigger unnecessary retries.
2. **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.
3. **Log deliveries**: Record incoming webhook requests. Logs are essential for diagnosing failed or out-of-order deliveries.
4. **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.
5. **Verify signatures**: Where applicable verify webhook signatures before processing events.