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

# Content and structure

> Read the envelope every V2 notification shares and find the event-specific data inside it.

Every notification Trio sends has the same JSON structure: an envelope that says which event happened and to what, and a `data` object with the details of the resource involved. This page explains the envelope; the [Events](https://docs.trio.com.br/v2/webhooks/events/overview.md) page lists what `data` contains for each category.

## The envelope

```json theme={null}
{
  "ref_id": "",
  "category": "",
  "type": "",
  "timestamp": "",
  "data": {}
}
```

| Field | Description |
| - | - |
| `ref_id` | ID of the resource the event refers to: the document, refund, recurrence or entity. |
| `category` | Category the event belongs to, such as `in_document` or `out_document`. |
| `type` | Type of the event within the category, such as `created`, `settled` or `failed`. |
| `timestamp` | Timestamp of the event, in the format described in [Date and time](https://docs.trio.com.br/v2/developers/date-and-time.md). |
| `data` | The resource in the state the event reports: the document, refund, recurrence or entity, with its own `id`. |

The examples on the Events page carry a few more envelope fields, such as `context_id` and `context_type`. They are not needed to handle a notification.

## Reading a notification

The notification below reports a cash-in document that settled: `category` and `type` say what happened, `ref_id` says to which document, and `data` carries the document itself. Amounts are in cents (BRL 100.00 = `10000`), so this payment is BRL 1.00.

```json theme={null}
{
  "data": {
    "amount": {
      "amount": 100,
      "currency": "BRL"
    },
    "counterparty": {
      "id": "29b6d0bc-7226-483b-99aa-aa815521ebb0",
      "name": "Conta 002",
      "tax_number": "45865162797606"
    },
    "description": null,
    "end_to_end_id": "E49931906202501311822NX1S6J7KaOm",
    "id": "0194bd99-65cd-5ee9-70f6-44d61ae5aa41",
    "receipt_url": "https://receipts.sandbox.trio.com.br/019108db-d49f-c744-5b79-736a2849ddf5/in/0194bd99-65cd-5ee9-70f6-44d61ae5aa41",
    "transaction_date": "2025-01-31T18:22:14.510717Z",
    "document_type": "pix",
    "bank_account_id": "0194412c-c559-5452-942e-7f4b4975c666"
  },
  "timestamp": "2025-01-31T18:22:14.477163Z",
  "type": "settled",
  "category": "in_document",
  "ref_id": "0194bd99-65cd-5ee9-70f6-44d61ae5aa41"
}
```

To handle it:

1. Route on `category` and `type`. Together they name the event, `in_document.settled` here.
2. Find your own record with `ref_id`, or with `data.external_id` when you sent one in the request that created the resource.
3. Update that record from `data`. If you prefer to read the current state from the API, fetch the resource by `ref_id`.

> [!TIP]
>
> Trio retries a notification your endpoint does not acknowledge in time, so the same event can arrive twice. Treat the combination of `ref_id`, `category` and `type` as the key of a notification and skip the ones you have already handled.

## Next steps

* [Events](https://docs.trio.com.br/v2/webhooks/events/overview.md): every category and type, with the `data` of each.
* [Webhook authentication](https://docs.trio.com.br/v2/webhooks/authentication.md): verify the body before you trust it.
* [Cash-in](https://docs.trio.com.br/v2/guides/receivables/cash-in.md) and [Cash-out](https://docs.trio.com.br/v2/guides/payments/cash-out.md): the flows that produce the main events.


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