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

# Delivery and retries

> How to acknowledge a webhook delivery, the retry schedule, when Trustware disables a webhook URL, and the limits on test events and redeliveries.

## Responding

Return any `2xx` status within 15 seconds to acknowledge a delivery. Trustware ignores the response body beyond its first 4 KiB, which it keeps for your [delivery log](https://docs.trustware.io/webhooks/dashboard-setup.md#read-the-delivery-log).

Everything else counts as a failed attempt and is retried:

| Your endpoint | Result |
| - | - |
| Any `2xx` within 15 seconds | Delivered. No more attempts. |
| `410 Gone` | Your webhook URL is **disabled immediately**. See [disabling](#when-your-webhook-url-is-disabled). |
| Any other `4xx` or `5xx` | Failed. Retried on the schedule below. |
| A `3xx` redirect | Failed. Trustware doesn't follow redirects, so register the final URL. |
| No response within 15 seconds | Failed (timeout). Retried. |
| Connection refused, TLS or DNS error | Failed. Retried. |

Acknowledge first, then do the work. If processing an event can take longer than a few seconds, record it and return `2xx`, then process it in the background. A slow handler that times out gets the same event again later.

Don't return `410` for an event you simply don't want. It disables delivery for your whole project. Return `2xx` and ignore the event instead.

### Slowing Trustware down

A `Retry-After` header on a failed response sets the earliest time of the next attempt. It can be a number of seconds or an HTTP date, and Trustware caps it at 24 hours. A value in neither form is ignored, and the normal schedule applies. A `429` or `503` with no `Retry-After` follows the normal schedule.

## Retry schedule

Each webhook event gets up to 10 attempts: the first right away, then retries after these delays, each counted from the previous failed attempt:

| Retry | Delay after the previous attempt |
| - | - |
| 1 | 5 seconds |
| 2 | 5 minutes |
| 3 | 30 minutes |
| 4 | 2 hours |
| 5 | 5 hours |
| 6 | 10 hours |
| 7 | 14 hours |
| 8 | 20 hours |
| 9 | 24 hours |

Each delay varies by up to 10% either way, so retries from many events don't all land at once. In total the schedule covers about 3 days.

Each attempt gets a new `webhook-timestamp` and a new signature. The `webhook-id`, `sequence` and body stay the same.

If every attempt fails, the webhook event is marked **failed** in your delivery log, and your project's owners and admins get an email. You can [redeliver](https://docs.trustware.io/webhooks/dashboard-setup.md#redeliver-webhook-events) a failed event once you've fixed your handler.

## Concurrency

Trustware has at most 5 deliveries in flight to one project's webhook URL at a time. Deliveries can arrive in parallel and in any order, even for the same route intent, so don't rely on one finishing before the next starts.

## When your webhook URL is disabled

Trustware disables your webhook URL when either of these happens:

* your endpoint returns `410 Gone` to any delivery, including a test event or a redelivery
* a webhook event uses up all 10 attempts, and your endpoint hasn't returned a `2xx` to any delivery in the last 72 hours

When Trustware disables your URL, your project's owners and admins get an email, and the dashboard shows why it was disabled. You can also disable it yourself from the dashboard.

While your URL is disabled:

* webhook events are still recorded for every change
* nothing is sent, and retries that were scheduled are cancelled
* test events and redeliveries are refused

When you re-enable it, new webhook events are sent again. Events recorded while it was disabled aren't sent automatically. Use **Redeliver undelivered** in the dashboard to send every undelivered event from the last 30 days that was recorded after you registered the URL. Because each event keeps its `sequence`, your handler can apply that backlog late without overwriting newer state.

## Retention

Trustware keeps webhook events and delivery attempts for 30 days. After that they leave the delivery log and can't be redelivered. For anything older, read the route intent from [`/status`](https://docs.trustware.io/api-reference/status).

## Limits on test events and redeliveries

Sending test events and redeliveries from the dashboard is limited per project:

| Action | Limit |
| - | - |
| Test events | 10 a minute |
| Single redeliveries | 30 a minute |
| Redeliver undelivered | Once every 5 minutes |

Over a limit, the dashboard shows an error saying how long to wait. Each limit counts separately, and a request refused for another reason, such as a disabled URL, doesn't count. These limits apply only to sends you start from the dashboard. Webhook events that route intents fire aren't limited.

## Webhook URL requirements

Trustware checks your URL when you register or change it, and again on every delivery. The URL must:

* use `https`, on port 443
* have a hostname that resolves only to public IP addresses
* have no username or password, and no `#fragment`
* be at most 2,048 bytes long

A hostname that resolves to a private, loopback or link-local address is refused, even if another of its addresses is public. If your hostname later starts resolving to such an address, deliveries to it fail and appear in your delivery log as blocked.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.