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

# Bank Webhooks: Link, Connection and Data Events

> The bank.link, bank.connection, bank.data and bank.sync webhook events: when each is sent, what it carries, and how to use it to drive your daily read.

Didit sends bank webhooks when a link ends, a connection changes, the consent is about to end, or a sync stores new data.
They use the same envelope, signing and retries as every other Didit webhook, and carry ids and statuses only: you fetch the object to read it.

> [!NOTE]
>
> Bank webhook events are sent for live and sandbox applications.
> Choose the events per destination with the destination's event filter, as for other events.
> See [Webhooks](https://docs.didit.me/integration/webhooks.md) for the envelope, the signature headers and retries.

## Events

| Event | When | Fields |
| - | - | - |
| `bank.link.completed` | A person connected a bank. | `data.link_id`, `data.status`, `data.connection_id`, `data.check_id`, `data.error_code` (always `null`) |
| `bank.link.cancelled` | The person cancelled. | `data.link_id`, `data.status` |
| `bank.link.expired` | The link expired before it was completed. | `data.link_id`, `data.status` |
| `bank.link.failed` | The link ended in an error. | `data.link_id`, `data.status`, `data.error_code` |
| `bank.connection.created` | The first sync finished and the accounts are readable. | `connection_id`, `initial_status` |
| `bank.connection.history_complete` | The history backfill ended, for any reason. | `connection_id`, `status` |
| `bank.connection.updated` | The status, the consent or the sync state changed. | `connection_id`, `status`, `revocation_status` |
| `bank.connection.consent_expiring` | 14, 7 and 1 day before the consent ends. | `connection_id`, `days_left`, `consent_expires_at`, `renew_by` |
| `bank.connection.renewal_required` | The consent ended, or the bank asks the person to sign in again. | `connection_id`, `status`, `reason`, `renew_by`, `renewable_until` |
| `bank.connection.renewed` | A renew link completed. | `connection_id`, `status`, `consent_version`, `link_id`, `consent_expires_at` |
| `bank.connection.revoked` | Access ended. | `connection_id`, `status`, `ended_by`, `status_reason`, `ended_at`, `retain_until` |
| `bank.connection.deleted` | The connection and its data were deleted. | `connection_id`, `status`, `erasure_status`, `reason`, `erased_at` |
| `bank.data.updated` | A sync stored changes. | `connection_id`, `sync_id`, `trigger`, `accounts` (ids with counts), `balances_changed` |
| `bank.sync.completed` | Every sync finished. | `connection_id`, `sync_id`, `trigger`, `outcome`, `changed` |
| `bank.sync.failed` | A sync keeps failing. | `connection_id`, `sync_id`, `error_code`, `failing_since` |
| `bank.sync.recovered` | A failing sync works again. | `connection_id`, `sync_id` |

Every event also carries the common fields `event_id`, `webhook_type`, `timestamp`, `created_at`, `application_id` and `environment`.
`bank.link.*` events carry their fields under `data`; the connection, data and sync events carry theirs at the top level.
`ended_by` is `end_user`, `bank`, `customer` or `unknown`.
The exact schema of every event is in the [API reference](https://docs.didit.me/standalone-apis/bank-data.md).

## Example

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

## How to use them

* **New data.** `bank.data.updated` is a signal only: nothing is pushed. Call the [change feed](https://docs.didit.me/standalone-apis/bank-transactions-sync.md) with your stored cursor. Use `bank.sync.completed` only if you want to see every sync, including those that changed nothing.
* **Onboarding.** Wait for `bank.connection.created` before you read accounts, and for `bank.connection.history_complete` before you rely on the full history.
* **Consent.** On `bank.connection.consent_expiring` ask the person to renew. On `bank.connection.renewal_required` data is still readable but no longer synced.
* **Stop.** On `bank.connection.revoked` stop your own feed for that connection and decide whether to [delete](https://docs.didit.me/standalone-apis/bank-connection-delete.md) the stored data.
* **Duplicates.** Treat every event idempotently: key on the event id, and expect the same event twice now and then.
* **Never trust the browser.** Confirm a link with `bank.link.completed` or `GET /v3/bank/links/{id}/`, not with a link id sent by a page.

## Next steps

* [Continuous bank feed for accounting](https://docs.didit.me/use-cases/bank-data-for-accounting.md)
* [Sandbox](https://docs.didit.me/core-technology/bank-verification/sandbox.md): the Didit Test Bank fires these events.


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