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

> The webhook request headers, the envelope fields, and example bodies for the pending and transaction shapes.

Each delivery is an HTTPS `POST` to your webhook URL with a JSON body. The body is an envelope around the route intent's `/status` body.

## Headers

| Header | Value |
| - | - |
| `webhook-id` | The webhook event's ID, a UUID. Unique per webhook event, and the same on every retry and redelivery. Use it to drop duplicates. |
| `webhook-timestamp` | When this attempt was sent, in Unix seconds. New on every attempt. |
| `webhook-signature` | One or more space-separated signatures, each `v1,` followed by base64. See [verify signatures](https://docs.trustware.io/webhooks/verify-signatures.md). |
| `content-type` | `application/json` |
| `user-agent` | `Trustware-Webhooks/1` |

The three `webhook-*` headers follow the [Standard Webhooks](https://www.standardwebhooks.com) v1.0.0 specification.

## Envelope

```json theme={null}
{
  "type": "route_intent.success",
  "timestamp": "2026-11-05T12:00:00Z",
  "apiVersion": "v1",
  "sequence": 4,
  "test": false,
  "data": { "...": "the /status body" }
}
```

| Field | Type | Description |
| - | - | - |
| `type` | string | The [event type](https://docs.trustware.io/webhooks/event-types.md). |
| `timestamp` | string | When the change happened, in UTC to the whole second. It never changes, even on a retry or redelivery. Not the same as the `webhook-timestamp` header, which is when the attempt was sent. |
| `apiVersion` | string | The `/status` API version that `data` follows. Currently always `"v1"`. |
| `sequence` | integer | This route intent's webhook event counter. Starts at 1 and goes up by exactly 1, with no gaps. If you've already processed an equal or higher `sequence` for the same route intent, ignore the event. |
| `test` | boolean | `true` for a [test event](https://docs.trustware.io/webhooks/dashboard-setup.md#send-a-test-event) sent from the Client Dashboard, `false` otherwise. Always present. |
| `data` | object | Exactly what [`GET /api/v1/route-intent/:intentId/status`](https://docs.trustware.io/api-reference/status) returns inside its `data` field, as the change left it. |

The envelope fields use camelCase. The fields inside `data` follow `/status`, which uses snake\_case in `v1`.

Bodies are at most 256 KiB. `data` can include `transaction_request`, the route's raw calldata, so set your server's body size limit to at least 256 KiB. Express's `express.raw()`, for example, defaults to 100 KB.

## The two `data` shapes

`data` has the same two shapes as `/status`.

### Pending shape

Before the route intent is committed, `data.status` is `"pending"` or `"expired"` and `data` has no transaction fields. `route_intent.expired` and `route_intent.approve_confirmed` carry this shape. For example, an approve step confirmed on a two-step route:

```json theme={null}
{
  "type": "route_intent.approve_confirmed",
  "timestamp": "2026-11-05T12:00:00Z",
  "apiVersion": "v1",
  "sequence": 1,
  "test": false,
  "data": {
    "create_date": "2026-11-05T11:58:00Z",
    "expiresAt": "2026-11-05T12:28:00Z",
    "intent_id": "00000000-0000-0000-0000-000000000000",
    "intent_status": "created",
    "status": "pending",
    "steps": [
      {
        "step_index": 0,
        "step_kind": "approve",
        "chain_id": "1",
        "tx_hash": "0x9a8b7c6d5e4f30211203f4e5d6c7b8a99a8b7c6d5e4f30211203f4e5d6c7b8a9",
        "status": "confirmed",
        "detail": {
          "token": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
          "spender": "0xce16f69375520ab01377ce7b88f5ba8c48f8d666",
          "amount": "25000000"
        },
        "create_date": "2026-11-05T11:58:00Z",
        "update_date": "2026-11-05T11:59:30Z"
      },
      {
        "step_index": 1,
        "step_kind": "main",
        "chain_id": "1",
        "status": "planned",
        "create_date": "2026-11-05T11:58:00Z",
        "update_date": "2026-11-05T11:58:00Z"
      }
    ]
  }
}
```

### Transaction shape

From the commit on, `data` is the transaction payload. Every other type carries this shape. For example, `route_intent.success`:

```json theme={null}
{
  "type": "route_intent.success",
  "timestamp": "2026-11-05T12:00:00Z",
  "apiVersion": "v1",
  "sequence": 4,
  "test": false,
  "data": {
    "id": "00000000-0000-0000-0000-0000000000a1",
    "intent_id": "00000000-0000-0000-0000-000000000000",
    "project_id": "00000000-0000-0000-0000-0000000000b1",
    "sdk_request": true,
    "from_address": "0x742d35cc6634c0532925a3b844bc454e4438f44e",
    "to_address": "0x742d35cc6634c0532925a3b844bc454e4438f44e",
    "sender_verification": "verified",
    "from_chain_id": "1",
    "to_chain_id": "8453",
    "source_tx_hash": "0x8f9d5c2a6b1e3f4071c8d2a9e5b6f3c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6",
    "dest_tx_hash": "0x5e4d3c2b1a09f8e7d6c5b4a39281706f5e4d3c2b1a09f8e7d6c5b4a392817060",
    "transaction_request": {
      "to": "0xce16f69375520ab01377ce7b88f5ba8c48f8d666",
      "data": "0x846a1bc6",
      "value": "0"
    },
    "status": "success",
    "from_chain_tx_url": "https://etherscan.io/tx/0x8f9d5c2a6b1e3f4071c8d2a9e5b6f3c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6",
    "to_chain_tx_url": "https://basescan.org/tx/0x5e4d3c2b1a09f8e7d6c5b4a39281706f5e4d3c2b1a09f8e7d6c5b4a392817060",
    "time_spent_ms": 84000,
    "quote_to_amount_usd": "24.97",
    "to_amount_wei": "24970000",
    "refunded": false,
    "routing_provider": "squid",
    "create_date": "2026-11-05T11:58:00Z",
    "update_date": "2026-11-05T12:00:00Z",
    "gas_sponsored": false
  }
}
```

These examples are the sample data the Client Dashboard sends as test events, so they use the zero route intent ID and placeholder hashes. A real webhook event carries real values, and includes every field `/status` would return at that moment. Optional fields such as `gas_status` appear only when `/status` would include them. See the [`/status` reference](https://docs.trustware.io/api-reference/status#response-fields) for what each field means.

Check `data.status` before reading any other field of `data`, the same way you would with a `/status` response.

## Parse after you verify

Verify the signature over the raw bytes first, then parse the JSON. A body you've parsed and re-serialized won't match the signature, because key order and whitespace can change. [Verify signatures](https://docs.trustware.io/webhooks/verify-signatures.md) shows how.


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