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

# Webhooks overview

> Trustware POSTs a signed webhook event to your server when a route intent changes, so your backend doesn't have to poll /status.

Without webhooks, your backend learns what happened to a deposit by polling [`GET /api/v1/route-intent/:intentId/status`](https://docs.trustware.io/api-reference/status) until it reaches `success` or `failed`. With webhooks, you register one HTTPS URL for your project in the [Client Dashboard](https://dashboard.trustware.io), and Trustware POSTs a webhook event to it whenever one of your project's route intents changes in a way you'd act on.

Each webhook event carries the same body `/status` would return at that moment, inside a small envelope. You don't need to call Trustware back to find out what changed.

## Polling or webhooks

| | Polling `/status` | Webhooks |
| - | - | - |
| Who starts the request | Your server, on a timer | Trustware, when something changes |
| Setup | An API key | A webhook URL and its signing secret, set in the Client Dashboard |
| What you receive | The current `/status` body | The `/status` body as the change left it, plus `type` and `sequence` |
| Timing | Your polling interval | Sent once the change is recorded, then retried for about 3 days if your endpoint fails |
| History | Any route intent, any time | Only changes made after you registered the URL |

`/status` keeps working exactly as before, and it stays the source of truth. Webhooks are additive: you can use both, and you should fall back to `/status` for anything that happened before you registered your URL.

Webhooks go from Trustware's servers to yours. They don't replace the widget's own status tracking. The widget runs in the payer's browser, which a webhook can't reach, so it keeps polling as it does today. No SDK change is needed to use webhooks.

## When a webhook event fires

A webhook event fires when a route intent:

* changes `status`: it's committed (`submitted`), starts `bridging`, reaches `success` or `failed`, or `expired`, including a late commit of an expired route intent
* has its source transaction replaced, so `source_tx_hash` changes
* has an approve step confirmed on a multi-step route, before the commit
* gets a `dest_tx_hash` for the first time

Nothing else fires one. Building a route with `POST /route` doesn't. Neither do routine updates that only refresh fields such as `update_date`, `poll_attempt` or `status_raw` while a route is in transit. [Event types](https://docs.trustware.io/webhooks/event-types.md) lists each type.

## What you need to handle

Delivery is **at least once** and **unordered**. Your handler needs to cope with both:

* **Duplicates.** The same webhook event can arrive more than once. The `webhook-id` header is unique per webhook event and stays the same on every retry and redelivery, so use it to drop exact duplicates.
* **Out of order.** Webhook events can arrive in a different order from the one they happened in. `sequence` counts one route intent's webhook events from 1, going up by exactly 1. If you've already processed an equal or higher `sequence` for that route intent, ignore the webhook event.
* **Unknown types.** Trustware may add new event types. Return `2xx` for any type you don't recognize, and ignore it.

A minimal handler:

1. Read the raw request body as bytes.
2. [Verify the signature](https://docs.trustware.io/webhooks/verify-signatures.md). Reject the request if it fails.
3. Drop it if you've already seen its `webhook-id`.
4. Drop it if you've already processed a higher or equal `sequence` for `data.intent_id`.
5. Record it, return `2xx` within 15 seconds, and do slow work after responding.

[Delivery and retries](https://docs.trustware.io/webhooks/delivery.md) covers what counts as a success, and what happens when your endpoint fails.

## Staging and production

If you run staging and production as separate projects, each has its own webhook URL and secret.

## Only new changes

A newly registered webhook URL receives webhook events for changes from that moment on. Trustware never sends webhook events for changes made before you registered. For those, use `/status`.

## API versions

Today the only API version is `v1`. The envelope fields (`type`, `timestamp`, `apiVersion`, `sequence`, `test` and `data`) are camelCase, and `data` follows the `v1` `/status` body, which is snake\_case.

## Next steps

> [card] [Event types](https://docs.trustware.io/webhooks/event-types.md)
>
> The eight types and when each one fires.

> [card] [Payload](https://docs.trustware.io/webhooks/payload.md)
>
> The envelope, the headers, and example bodies.

> [card] [Verify signatures](https://docs.trustware.io/webhooks/verify-signatures.md)
>
> Standard Webhooks v1 signatures, code samples, and a test vector.

> [card] [Set up in the dashboard](https://docs.trustware.io/webhooks/dashboard-setup.md)
>
> Register a URL, send test events, and read the delivery log.


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