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

# Webhooks

> Register a webhook so Trio notifies your system when a transaction or an onboarding changes state, choose the payload version, and learn how Trio delivers and retries each notification.

Most operations on Trio are asynchronous: a Pix payment, a boleto or an onboarding is accepted first and settles, fails or is approved later, in the background. A webhook is the URL Trio calls with an HTTP POST and a JSON payload each time one of those events happens, so your system reacts to the final state without polling the API.

## Register a webhook

You can register a webhook in two ways:

* In the [Trio App](https://app.sandbox.trio.com.br), following [Creating your first webhook](https://docs.trio.com.br/v2/guides/creating-your-first-webhook.md).
* Through the API, with [Create webhook](https://docs.trio.com.br/v2/api-reference/banking-api/developers/webhooks/create-webhook.md). All examples use the sandbox base URL `https://api.sandbox.trio.com.br`.

```http theme={null}
POST /v2/webhooks
```

```json theme={null}
{
  "notification_url": "https://mynotificationurl.com/endpoint",
  "notification_secret": "some_notification_secret",
  "authentication_method": "url_secret",
  "api_version": "v200",
  "entity_id": "019a1c2e-5b7d-7f80-9a1b-2c3d4e5f6a7c",
  "event_categories_allowed": [
    {
      "category": "boleto",
      "types": ["settled", "created"]
    }
  ]
}
```

| Field | Required | Description |
| - | - | - |
| `notification_url` | Yes | URL the events are sent to. |
| `notification_secret` | For `url_secret` | Secret sent with every event in the `x-webhook-secret` header. |
| `authentication_method` | Yes | How Trio authenticates to the notification URL: `url_secret` or `oauth`. See [Webhook authentication](https://docs.trio.com.br/v2/webhooks/authentication.md). |
| `oauth_client_id`, `oauth_client_secret`, `oauth_url`, `oauth_scope` | For `oauth` | OAuth client ID, client secret, token URL and scope. An `oauth` webhook sends these instead of `notification_secret`. |
| `api_version` | No | Version of the event payloads sent to the webhook: `v100` (default) or `v200`. See below. |
| `entity_id` | No | Entity to limit the webhook to. Leave it out to receive the events of every entity. |
| `group_id` | No | Group of the entity to limit the webhook to. |
| `event_categories_allowed` | No | Events to send to the webhook, as a list of `category` with its `types`. Empty or null sends every event; an empty `types` sends every type of the category. |

The response is the webhook, with its `id` and a generated `notification_key`: the key Trio signs the events with. Store the key; you need it to verify every notification you receive.

```json theme={null}
{
  "api_version": "v200",
  "authentication_method": "url_secret",
  "entity_id": "019a1c2e-5b7d-7f80-9a1b-2c3d4e5f6a7c",
  "event_categories_allowed": [
    {
      "category": "boleto",
      "types": ["settled", "created"]
    }
  ],
  "group_id": null,
  "id": "019a1c2e-5b7d-7f80-9a1b-2c3d4e5f6a7b",
  "inserted_at": "2026-10-01T12:00:00.000000Z",
  "notification_key": "KXe1JxmdHIcRhAsnbaTBvSGNSQli4I798oGMb8abeMBcKzJoUpWkOQ==",
  "notification_secret": "some_notification_secret",
  "notification_url": "https://mynotificationurl.com/endpoint",
  "updated_at": "2026-10-01T12:00:00.000000Z"
}
```

## Choose the payload version

`api_version` selects the version of the event payloads Trio sends to the webhook. The version belongs to the webhook, not to your API credential, so you can register a second webhook on `v200` and compare its payloads with the ones you already handle before switching.

| Version | What the webhook receives |
| - | - |
| `v100` (default, and every webhook created without a version) | The legacy payloads: categories named `collecting_document`, `payment_document` and so on, accounts named `virtual_account_id`, and no `stages`. These are the payloads documented for V1. |
| `v200` | The V2 payloads: categories named after the V2 resources (`in_document`, `out_document`, `boleto`...), accounts named `bank_account_id` and `group_id`, nested `counterparty` and `reference` objects where the resource has them, and the resource's `stages`. These are the payloads documented in [Events](https://docs.trio.com.br/v2/webhooks/events/overview.md). |

Both versions share the same envelope, described in [Content and structure](https://docs.trio.com.br/v2/webhooks/content-and-structure.md). Onboarding events (category `entity`) have a single format and are sent to webhooks of both versions.

## Choose which events you receive

By default a webhook receives every event of your organization. Three optional fields narrow it down:

* `event_categories_allowed` lists the categories and types you want. For example, `{ "category": "boleto", "types": ["settled", "created"] }` delivers only those two boleto events; `"types": []` delivers every type of the category. The types are the ones listed on the [Events](https://docs.trio.com.br/v2/webhooks/events/overview.md) page. In `event_categories_allowed` the four document categories still use their V1 names, even for a `v200` webhook: write `collecting_document` for `in_document`, `collecting_document_refund` for `in_document_refund`, `payment_document` for `out_document` and `payment_document_refund` for `out_document_refund`. The V2 document names are refused with `422` in this field; every other category uses the same name in the filter and in the notification.
* `entity_id` limits the webhook to the events of one entity.
* `group_id` limits it to the events of one group of that entity.

> [!WARNING]
>
> Today the three filters apply to `v100` webhooks and to `entity` events. A `v200` webhook receives every event of the eleven V2 categories of the organization, whatever its `event_categories_allowed`, `entity_id` and `group_id`. Filter on `category`, `type` and `data.entity_id` in your handler until this changes.

## Delivery and retries

Trio delivers every notification as an HTTP POST with a JSON body to `notification_url`, with the headers described in [Webhook authentication](https://docs.trio.com.br/v2/webhooks/authentication.md). Your endpoint must accept that method and content type.

* **Acknowledge fast.** Trio waits 1 second for the response. A `200`, `201`, `202` or `204` status marks the notification as delivered.
* **Errors are retried.** When your endpoint answers any other status, refuses the connection or fails the TLS handshake, Trio queues the notification for retry. The first retry comes 5 seconds after the failure and the wait doubles at each new failure, up to 3 minutes between attempts. Trio stops after 24 attempts or 1 hour after the first failure, whichever comes first.
* **Timeouts are not retried.** A notification your endpoint does not answer within 1 second is logged as a timeout and is not sent again. Read the resource back from the API if you suspect you missed an event.
* Serve the endpoint over HTTPS so the payload is protected in transit.

> [!TIP]
>
> Answer with a `2XX` as soon as you have stored the notification and do the heavy work afterwards. A retried notification carries the same event again, so keep your processing idempotent: treat `ref_id`, `category` and `type` together as the key of a notification.

## Manage webhooks

Every webhook of the organization is managed through the API or the Trio App:

* [List webhooks](https://docs.trio.com.br/v2/api-reference/banking-api/developers/webhooks/list-webhooks.md) returns every webhook in a single page; the list is not paginated.
* [Get webhook](https://docs.trio.com.br/v2/api-reference/banking-api/developers/webhooks/get-webhook.md) returns one webhook, including its `notification_key`.
* [Replace webhook](https://docs.trio.com.br/v2/api-reference/banking-api/developers/webhooks/replace-webhook.md) replaces a webhook with the one you send. Send every field: an omitted field is cleared, so leaving out `entity_id` or `event_categories_allowed` removes that filter.
* [Delete webhook](https://docs.trio.com.br/v2/api-reference/banking-api/developers/webhooks/delete-webhook.md) stops the deliveries.

## Next steps

* [Webhook authentication](https://docs.trio.com.br/v2/webhooks/authentication.md): verify that a notification came from Trio.
* [Content and structure](https://docs.trio.com.br/v2/webhooks/content-and-structure.md): read the envelope every notification shares.
* [Events](https://docs.trio.com.br/v2/webhooks/events/overview.md): every category and type, with the `data` of each.
* [Creating your first webhook](https://docs.trio.com.br/v2/guides/creating-your-first-webhook.md): register a webhook from the Trio App, step by step.


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