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

# Webhooks bancários: eventos de vínculo, conexão e dados

> Didit envia os eventos bank.link, bank.connection, bank.data e bank.sync: quando saem, o que contêm e como usá-los na leitura diária.

Didit envia webhooks bancários quando um link é encerrado, uma conexão muda, o consentimento está prestes a expirar ou uma sincronização armazena novos dados.
Eles usam o mesmo envelope, a mesma assinatura e as mesmas tentativas de reenvio de todos os outros webhooks da Didit, e trazem apenas IDs e status: para ler o objeto, você precisa buscá-lo.

> [!NOTE]
>
> Os eventos de webhook bancário são enviados para aplicações de produção e sandbox.
> Escolha os eventos por destino, com o filtro de eventos do destino, como para os demais eventos.
> Consulte [Webhooks](https://docs.didit.me/pt-br/integration/webhooks.md) para o envelope, os cabeçalhos de assinatura e as tentativas de reenvio.

## Eventos

| Evento | Quando | Campos |
| - | - | - |
| `bank.link.completed` | Uma pessoa conectou um banco. | `data.link_id`, `data.status`, `data.connection_id`, `data.check_id`, `data.error_code` (sempre `null`) |
| `bank.link.cancelled` | A pessoa cancelou. | `data.link_id`, `data.status` |
| `bank.link.expired` | O link expirou antes de ser concluído. | `data.link_id`, `data.status` |
| `bank.link.failed` | O link terminou com erro. | `data.link_id`, `data.status`, `data.error_code` |
| `bank.connection.created` | A primeira sincronização terminou e as contas podem ser lidas. | `connection_id`, `initial_status` |
| `bank.connection.history_complete` | A carga do histórico terminou, por qualquer motivo. | `connection_id`, `status` |
| `bank.connection.updated` | O status, o consentimento ou o estado da sincronização mudou. | `connection_id`, `status`, `revocation_status` |
| `bank.connection.consent_expiring` | 14, 7 e 1 dia antes do fim do consentimento. | `connection_id`, `days_left`, `consent_expires_at`, `renew_by` |
| `bank.connection.renewal_required` | O consentimento terminou, ou o banco pede que a pessoa faça login novamente. | `connection_id`, `status`, `reason`, `renew_by`, `renewable_until` |
| `bank.connection.renewed` | Um link de renovação foi concluído. | `connection_id`, `status`, `consent_version`, `link_id`, `consent_expires_at` |
| `bank.connection.revoked` | O acesso foi encerrado. | `connection_id`, `status`, `ended_by`, `status_reason`, `ended_at`, `retain_until` |
| `bank.connection.deleted` | A conexão e os seus dados foram excluídos. | `connection_id`, `status`, `erasure_status`, `reason`, `erased_at` |
| `bank.data.updated` | Uma sincronização armazenou alterações. | `connection_id`, `sync_id`, `trigger`, `accounts` (ids com contagens), `balances_changed` |
| `bank.sync.completed` | Todas as sincronizações terminaram. | `connection_id`, `sync_id`, `trigger`, `outcome`, `changed` |
| `bank.sync.failed` | Uma sincronização continua falhando. | `connection_id`, `sync_id`, `error_code`, `failing_since` |
| `bank.sync.recovered` | Uma sincronização que falhava voltou a funcionar. | `connection_id`, `sync_id` |

Todos os eventos também trazem os campos comuns `event_id`, `webhook_type`, `timestamp`, `created_at`, `application_id` e `environment`.
Os eventos `bank.link.*` trazem seus campos dentro de `data`; os eventos de conexão, dados e sincronização trazem os seus no nível superior.
`ended_by` pode ser `end_user`, `bank`, `customer` ou `unknown`.
O esquema exato de cada evento está na [Referência da API](https://docs.didit.me/pt-br/standalone-apis/bank-data.md).

## Exemplo

```json theme={null}
{
  "event_id": "7c1e0a52-93d4-4a6b-8f21-0d5b9e3a64c7",
  "webhook_type": "bank.sync.completed",
  "timestamp": 1763804640,
  "created_at": 1763804640,
  "application_id": "b3e1f0a2-5d64-4c8e-9a17-2f6d0c8b7e41",
  "environment": "sandbox",
  "connection_id": "5e1d2a70-3b4c-4d5e-8f60-71829304a5b6",
  "sync_id": "c2b8d4f6-9a13-4e07-85bc-3d6e1f0a7b92",
  "trigger": "scheduled",
  "outcome": "succeeded",
  "changed": true
}
```

## Como usar os eventos

* **Dados novos.** `bank.data.updated` é apenas um sinal: nada é enviado. Chame o [feed de alterações](https://docs.didit.me/pt-br/standalone-apis/bank-transactions-sync.md) com o cursor armazenado. Use `bank.sync.completed` apenas se quiser ver todas as sincronizações, inclusive as que não alteraram nada.
* **Onboarding.** Aguarde `bank.connection.created` antes de ler as contas, e `bank.connection.history_complete` antes de depender do histórico completo.
* **Consentimento.** Ao receber `bank.connection.consent_expiring`, peça à pessoa que renove o consentimento. Ao receber `bank.connection.renewal_required`, os dados ainda podem ser lidos, mas não são mais sincronizados.
* **Encerramento.** Ao receber `bank.connection.revoked`, interrompa o seu próprio feed para essa conexão e decida se deseja [excluir](https://docs.didit.me/pt-br/standalone-apis/bank-connection-delete.md) os dados armazenados.
* **Duplicatas.** Trate todo evento de forma idempotente: use o id do evento como chave e esteja preparado para receber o mesmo evento duas vezes de tempos em tempos.
* **Nunca confie no navegador.** Confirme um link com `bank.link.completed` ou `GET /v3/bank/links/{id}/`, e não com um id de link enviado por uma página.

## Próximos passos

* [Feed bancário contínuo para contabilidade](https://docs.didit.me/pt-br/use-cases/bank-data-for-accounting.md)
* [Sandbox](https://docs.didit.me/pt-br/core-technology/bank-verification/sandbox.md): o Didit Test Bank dispara esses eventos.


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