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

# Webhooks

> Subscribe to real-time event notifications for banking transactions and exceptions on the Tesouro platform.

Webhooks let your system receive real-time notifications when events occur on the Tesouro platform.
Tesouro delivers these as HTTP POST requests to an endpoint you register.
Unlike polling the API, webhooks push data to you when an event occurs reducing latency and API load.

<Warning>
  Your endpoint must return a `2xx` status code to acknowledge receipt. Process payloads
  asynchronously. Heavy processing in the request handler risks timeouts and failed deliveries.
</Warning>

## How it works

Embedded banking webhooks use a subscription model. You explicitly subscribe to the event types you want to receive, and Tesouro delivers matching events to your registered endpoint.
Each subscription is created and managed through the [managing subscriptions guide](/embedded-banking/guides/webhooks/managing-subscriptions).

## Supported events

| Event type                    | Description                                       |
| :---------------------------- | :------------------------------------------------ |
| `LEDGER_TRANSACTION`          | A monetary transaction was posted to the ledger   |
| `LEDGER_POSTING_EXCEPTION`    | An exception occurred while posting a transaction |
| `LEDGER_ACCOUNT_EXCEPTION`    | An exception occurred on a ledger account         |
| `ACCOUNT_STATUS_CHANGED`      | A ledger account's status changed                 |
| `ACCOUNT_RESTRICTION_CHANGED` | A ledger account's restrictions changed           |

See [Event types](/embedded-banking/guides/webhooks/event-types) for the attributes and example payload for each event.

## Payload structure

Every webhook delivery shares the same envelope. Only the `eventType` value and the contents of `attributes` differ between events.

| Field                 | Type                   | Description                                                                                                                       |
| :-------------------- | :--------------------- | :-------------------------------------------------------------------------------------------------------------------------------- |
| `version`             | string                 | Payload schema version. Currently `"1"`.                                                                                          |
| `deliveryId`          | string (UUID)          | Identifier for this delivery. Stable across retry attempts of the same event - use it to deduplicate on your end.                 |
| `webhookUrl`          | string                 | The endpoint URL Tesouro is delivering to.                                                                                        |
| `deliveryDateTimeUtc` | string (ISO 8601, UTC) | Server timestamp of the delivery attempt.                                                                                         |
| `attemptCount`        | string                 | Delivery attempt number - `"1"` on first attempt, higher on retries.                                                              |
| `eventType`           | string                 | The event type. See [Event types](/embedded-banking/guides/webhooks/event-types).                                                 |
| `attributes`          | object                 | Event-specific fields. See [Event types](/embedded-banking/guides/webhooks/event-types) for the shape of each event's attributes. |

## Next steps

* [Managing subscriptions](/embedded-banking/guides/webhooks/managing-subscriptions): create and manage your webhook subscriptions
* [Event types](/embedded-banking/guides/webhooks/event-types): payload schemas for each event
* [Delivery and retry behavior](/embedded-banking/guides/webhooks/delivery-and-retry-behavior): how Tesouro delivers events and retries failures