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

# Webhook event types

> The eight route intent webhook event types, when each fires, and which /status shape its data carries.

Every webhook event has a `type`. A status change is named after the new `status` value, so the types reuse the words `/status` already uses: the commit is `route_intent.submitted`, not "committed".

| Type | Sent when | `data` shape |
| - | - | - |
| `route_intent.submitted` | The route intent is committed: by your receipt call, by Trustware's own watcher seeing the transaction, or late, after the route intent had `expired` | Transaction |
| `route_intent.bridging` | The routing provider reports the transfer in progress | Transaction |
| `route_intent.success` | The transfer completed | Transaction |
| `route_intent.failed` | The transfer failed. This includes refunds | Transaction |
| `route_intent.expired` | The route intent had no commit 24 hours after its `expiresAt` | Pending |
| `route_intent.source_tx_replaced` | A replacement transaction took over, so `source_tx_hash` changed | Transaction |
| `route_intent.approve_confirmed` | An approve step was confirmed on a multi-step route, before the commit | Pending |
| `route_intent.destination_tx_seen` | `dest_tx_hash` appeared for the first time | Transaction |

The `data` shapes are the two shapes `/status` returns: the [pending payload](https://docs.trustware.io/api-reference/status.md#the-pending-response) before a commit, and the [transaction payload](https://docs.trustware.io/api-reference/status.md#response-fields) after it. [Payload](https://docs.trustware.io/webhooks/payload.md) has an example of each.

> [!NOTE]
>
> Trustware may add event types. Return `2xx` for any type you don't
> recognize, and ignore it. Don't treat an unknown type as an error, or your
> endpoint will fail deliveries it should have accepted.

## Which types end a route intent

`route_intent.success` and `route_intent.failed` are final for the transfer.

`route_intent.expired` is final unless the transaction lands late. If the payer's transaction is committed after expiry, you receive `route_intent.submitted` and the route intent carries on from there. Don't release or reuse anything tied to the route intent on `expired` alone if a late payment would still matter to you.

## Refunds arrive as `failed`

A refunded transfer is reported as `failed`, the same way `/status` reports it. There's no separate refund type. `data.refunded` is `true` when the routing provider reported that it returned the input to the sender. A `false` doesn't rule out a refund, because refund reporting is provider dependent. Don't trigger any downstream payout until you receive `route_intent.success`.

## One change, several events

One update can fire more than one type. For example, a status check that sees the transfer complete and the destination transaction at the same time fires `route_intent.success` and `route_intent.destination_tx_seen` together. They get consecutive `sequence` numbers and carry the same `data`, so you can handle each independently.

When that happens, the events are numbered in this order:

1. the status type, if `status` changed
2. `route_intent.source_tx_replaced`
3. `route_intent.destination_tx_seen`
4. one `route_intent.approve_confirmed` per newly confirmed approve step, by step index

Delivery order isn't promised, so use `sequence` rather than arrival order to tell which came first.

## A typical sequence

Here is one possible sequence for a deposit that completes normally:

| `sequence` | `type` | `data.status` |
| - | - | - |
| 1 | `route_intent.submitted` | `submitted` |
| 2 | `route_intent.bridging` | `bridging` |
| 3 | `route_intent.success` | `success` |
| 4 | `route_intent.destination_tx_seen` | `success` |

The types you receive depend on the route and on what the routing provider reports, so don't hard-code this order. `route_intent.destination_tx_seen` can arrive while the route intent is still `bridging`, and a route that needs a token approval starts with one or more `route_intent.approve_confirmed` events before `route_intent.submitted`.


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