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

# Webhook authentication

> Choose how Trio authenticates to your notification URL and verify that each notification was sent by Trio and not altered in transit.

A V2 webhook has two layers of authentication. `authentication_method` chooses how Trio identifies itself to your notification URL: with a shared secret (`url_secret`) or with an OAuth token (`oauth`). On top of that, Trio signs every notification with the webhook's `notification_key`, so you can check that the body came from Trio and was not changed on the way.

> [!NOTE]
>
> Coming from V1? The **Secret** you type in the Trio App is the `notification_secret` of the API, and the webhook key shown in the webhook details is the `notification_key`.

## Authentication method

Set `authentication_method` when you [register the webhook](https://docs.trio.com.br/v2/webhooks/introduction.md#register-a-webhook). The method decides which other fields the webhook needs.

### Shared secret

A `url_secret` webhook needs `notification_url` and `notification_secret`. Trio sends the secret with every notification in the HTTP header `x-webhook-secret`, so your endpoint compares it with the value you stored and rejects the request when it differs.

### OAuth

An `oauth` webhook needs `oauth_client_id`, `oauth_client_secret`, `oauth_url` and `oauth_scope` instead of `notification_secret`. Trio obtains an access token from `oauth_url` with those credentials and uses it to authenticate its requests to `notification_url`.

| Field | Required | Description |
| - | - | - |
| `oauth_client_id` | Yes | OAuth client ID. |
| `oauth_client_secret` | Yes | OAuth client secret. |
| `oauth_url` | Yes | OAuth token URL Trio requests the token from. |
| `oauth_scope` | Yes | OAuth scope Trio requests. |

## Headers of a notification

Every notification is an HTTP POST with these headers:

| Header | Value |
| - | - |
| `content-type` | `application/json` |
| `x-webhook-secret` | The webhook's `notification_secret`. |
| `x-webhook-signature` | The HMAC-SHA-256 signature of the body, described below. |

## Signature

Every notification is signed with the webhook's `notification_key`, the key Trio generates when the webhook is created. The key is returned by [Create webhook](https://docs.trio.com.br/v2/api-reference/banking-api/developers/webhooks/create-webhook.md) and [Get webhook](https://docs.trio.com.br/v2/api-reference/banking-api/developers/webhooks/get-webhook.md), and shown in the webhook details of the Trio App.

The signature travels in the HTTP header `x-webhook-signature`. Trio computes it over the exact bytes of the request body. To verify it:

1. Compute the HMAC-SHA-256 of the raw request body with `notification_key` as the key.
2. Encode the result as uppercase hexadecimal.
3. Compare it with the header value using a constant-time comparison.

```javascript theme={null}
import { createHmac, timingSafeEqual } from "crypto"

// rawBody is the request body exactly as received, before any JSON parsing
const expectedSignature = req.headers["x-webhook-signature"]
const signatureKey = "your_notification_key"

const computedSignature = createHmac("sha256", signatureKey)
	.update(rawBody)
	.digest("hex")
	.toUpperCase()

const isValid = timingSafeEqual(
	Buffer.from(expectedSignature),
	Buffer.from(computedSignature)
)
```

> [!WARNING]
>
> Sign the raw body, not a re-serialized copy. If your framework parses the JSON before your handler runs, `JSON.stringify(req.body)` can reorder keys or change number formatting and the signature will not match. Keep the raw body available to the handler.

A webhook created without a `notification_key` receives an empty `x-webhook-signature` header. Every webhook created through the API or the Trio App has a key.

If your `notification_key` is accidentally made public, [contact support](https://docs.trio.com.br/v2/getting_started/support.md). Trio rotates the key and coordinates the change with you.

## Next steps

* [Content and structure](https://docs.trio.com.br/v2/webhooks/content-and-structure.md): what is inside the body you just verified.
* [Events](https://docs.trio.com.br/v2/webhooks/events/overview.md): every category and type Trio sends.
* [Creating your first webhook](https://docs.trio.com.br/v2/guides/creating-your-first-webhook.md): where the secret and the key appear in the Trio App.


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