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

# Webhook bancari: eventi bank.link, bank.connection, bank.data e bank.sync

> Didit invia gli eventi bank.link, bank.connection, bank.data e bank.sync: quando partono, cosa contengono e come usarli per la lettura quotidiana.

Didit invia i webhook bancari quando un link si conclude, una connessione cambia, il consenso sta per scadere o una sincronizzazione memorizza nuovi dati.
Usano la stessa struttura, la stessa firma e gli stessi tentativi di qualsiasi altro webhook Didit, e contengono solo ID e stati: per leggerne il contenuto devi recuperare l'oggetto.

> [!NOTE]
>
> Gli eventi webhook bancari vengono inviati per le applicazioni di produzione e sandbox.
> Scegli gli eventi per destinazione con il filtro eventi della destinazione, come per gli altri eventi.
> Consulta [Webhook](https://docs.didit.me/it/integration/webhooks.md) per la struttura, le intestazioni di firma e i tentativi.

## Eventi

| Evento | Quando | Campi |
| - | - | - |
| `bank.link.completed` | L'utente ha collegato una banca. | `data.link_id`, `data.status`, `data.connection_id`, `data.check_id`, `data.error_code` (sempre `null`) |
| `bank.link.cancelled` | L'utente ha annullato. | `data.link_id`, `data.status` |
| `bank.link.expired` | Il link è scaduto prima di essere completato. | `data.link_id`, `data.status` |
| `bank.link.failed` | Il link si è concluso con un errore. | `data.link_id`, `data.status`, `data.error_code` |
| `bank.connection.created` | La prima sincronizzazione è terminata e i conti sono leggibili. | `connection_id`, `initial_status` |
| `bank.connection.history_complete` | Il recupero retroattivo dello storico è terminato, per qualsiasi motivo. | `connection_id`, `status` |
| `bank.connection.updated` | Sono cambiati lo stato, il consenso o lo stato della sincronizzazione. | `connection_id`, `status`, `revocation_status` |
| `bank.connection.consent_expiring` | 14, 7 e 1 giorno prima della scadenza del consenso. | `connection_id`, `days_left`, `consent_expires_at`, `renew_by` |
| `bank.connection.renewal_required` | Il consenso è scaduto, oppure la banca chiede all'utente di accedere di nuovo. | `connection_id`, `status`, `reason`, `renew_by`, `renewable_until` |
| `bank.connection.renewed` | Un link di rinnovo è stato completato. | `connection_id`, `status`, `consent_version`, `link_id`, `consent_expires_at` |
| `bank.connection.revoked` | L'accesso è terminato. | `connection_id`, `status`, `ended_by`, `status_reason`, `ended_at`, `retain_until` |
| `bank.connection.deleted` | La connessione e i suoi dati sono stati eliminati. | `connection_id`, `status`, `erasure_status`, `reason`, `erased_at` |
| `bank.data.updated` | Una sincronizzazione ha memorizzato delle modifiche. | `connection_id`, `sync_id`, `trigger`, `accounts` (ID con conteggi), `balances_changed` |
| `bank.sync.completed` | Tutte le sincronizzazioni sono terminate. | `connection_id`, `sync_id`, `trigger`, `outcome`, `changed` |
| `bank.sync.failed` | Una sincronizzazione continua a non riuscire. | `connection_id`, `sync_id`, `error_code`, `failing_since` |
| `bank.sync.recovered` | Una sincronizzazione che non riusciva funziona di nuovo. | `connection_id`, `sync_id` |

Ogni evento contiene anche i campi comuni `event_id`, `webhook_type`, `timestamp`, `created_at`, `application_id` ed `environment`.
Gli eventi `bank.link.*` riportano i propri campi sotto `data`; gli eventi di connessione, dati e sincronizzazione li riportano al livello superiore.
`ended_by` può assumere i valori `end_user`, `bank`, `customer` o `unknown`.
Lo schema esatto di ogni evento è nel [riferimento API](https://docs.didit.me/it/standalone-apis/bank-data.md).

## Esempio

```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
}
```

## Come usarli

* **Nuovi dati.** `bank.data.updated` è solo un segnale: non viene inviato alcun dato. Chiama il [feed delle modifiche](https://docs.didit.me/it/standalone-apis/bank-transactions-sync.md) con il cursore che hai memorizzato. Usa `bank.sync.completed` solo se vuoi vedere ogni sincronizzazione, anche quelle che non hanno modificato nulla.
* **Onboarding.** Attendi `bank.connection.created` prima di leggere i conti, e `bank.connection.history_complete` prima di fare affidamento sullo storico completo.
* **Consenso.** Su `bank.connection.consent_expiring` chiedi alla persona di rinnovarlo. Su `bank.connection.renewal_required` i dati sono ancora leggibili ma non vengono più sincronizzati.
* **Stop.** Su `bank.connection.revoked` interrompi il tuo feed per quella connessione e decidi se [eliminare](https://docs.didit.me/it/standalone-apis/bank-connection-delete.md) i dati memorizzati.
* **Duplicati.** Gestisci ogni evento in modo idempotente: usa l'ID dell'evento come chiave, e aspettati che lo stesso evento arrivi due volte ogni tanto.
* **Non fidarti mai del browser.** Conferma un link con `bank.link.completed` o `GET /v3/bank/links/{id}/`, non con un ID di link inviato da una pagina.

## Passaggi successivi

* [Feed bancario continuo per la contabilità](https://docs.didit.me/it/use-cases/bank-data-for-accounting.md)
* [Sandbox](https://docs.didit.me/it/core-technology/bank-verification/sandbox.md): il Didit Test Bank genera questi eventi.


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