> ## 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：链接、连接与数据事件

> Didit 的 bank.link、bank.connection、bank.data 和 bank.sync Webhook 事件：说明各事件的触发时机和包含内容，以及如何用它们驱动每日银行数据读取。

Didit 会在链接结束、连接发生变化、同意即将到期，或同步存储新数据时发送银行 Webhook。
它们与 Didit 其他 Webhook 使用相同的消息封装格式、签名和重试机制，且仅包含 ID 和状态。您需要获取对应对象才能读取其内容。

> [!NOTE]
>
> 银行 Webhook 事件会为生产环境应用和沙盒应用发送。
> 请使用 Webhook 目标的事件过滤器为每个目标选择事件，与其他事件的做法相同。
> 消息封装格式、签名请求头和重试机制的说明，请参阅 [Webhooks](https://docs.didit.me/zh/integration/webhooks.md)。

## 事件

| 事件 | 触发时机 | 字段 |
| - | - | - |
| `bank.link.completed` | 用户已连接银行。 | `data.link_id`、`data.status`、`data.connection_id`、`data.check_id`、`data.error_code`（始终为 `null`） |
| `bank.link.cancelled` | 用户已取消。 | `data.link_id`、`data.status` |
| `bank.link.expired` | 链接在完成前已过期。 | `data.link_id`、`data.status` |
| `bank.link.failed` | 链接因错误而结束。 | `data.link_id`、`data.status`、`data.error_code` |
| `bank.connection.created` | 首次同步完成，账户数据可读取。 | `connection_id`、`initial_status` |
| `bank.connection.history_complete` | 历史数据回填结束，无论原因为何。 | `connection_id`、`status` |
| `bank.connection.updated` | 状态、同意或同步状态发生变化。 | `connection_id`、`status`、`revocation_status` |
| `bank.connection.consent_expiring` | 同意到期前 14 天、7 天和 1 天。 | `connection_id`、`days_left`、`consent_expires_at`、`renew_by` |
| `bank.connection.renewal_required` | 同意已结束，或银行要求用户重新登录。 | `connection_id`、`status`、`reason`、`renew_by`、`renewable_until` |
| `bank.connection.renewed` | 续期链接已完成。 | `connection_id`、`status`、`consent_version`、`link_id`、`consent_expires_at` |
| `bank.connection.revoked` | 访问权限已终止。 | `connection_id`、`status`、`ended_by`、`status_reason`、`ended_at`、`retain_until` |
| `bank.connection.deleted` | 连接及其数据已删除。 | `connection_id`、`status`、`erasure_status`、`reason`、`erased_at` |
| `bank.data.updated` | 一次同步存储了变更。 | `connection_id`、`sync_id`、`trigger`、`accounts`（包含 ID 和计数）、`balances_changed` |
| `bank.sync.completed` | 所有同步均已完成。 | `connection_id`、`sync_id`、`trigger`、`outcome`、`changed` |
| `bank.sync.failed` | 同步持续失败。 | `connection_id`、`sync_id`、`error_code`、`failing_since` |
| `bank.sync.recovered` | 失败的同步已恢复正常。 | `connection_id`、`sync_id` |

每个事件还包含以下公共字段：`event_id`、`webhook_type`、`timestamp`、`created_at`、`application_id` 和 `environment`。

`bank.link.*` 事件的字段位于 `data` 下；连接、数据和同步事件的字段位于顶层。

`ended_by` 的取值为 `end_user`、`bank`、`customer` 或 `unknown`。

每个事件的确切结构请参阅 [API 参考](https://docs.didit.me/zh/standalone-apis/bank-data.md)。

## 示例

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

## 如何使用

* **新数据。** `bank.data.updated` 仅是信号，不会推送任何数据。请使用已存储的游标调用[变更流](https://docs.didit.me/zh/standalone-apis/bank-transactions-sync.md)。只有当您希望查看每次同步（包括未产生任何变更的同步）时，才使用 `bank.sync.completed`。
* **入驻。** 在读取账户之前，请等待 `bank.connection.created`；在依赖完整历史记录之前，请等待 `bank.connection.history_complete`。
* **同意。** 收到 `bank.connection.consent_expiring` 时，请用户续期。收到 `bank.connection.renewal_required` 时，数据仍可读取，但不再同步。
* **停止。** 收到 `bank.connection.revoked` 时，请停止该连接对应的自有数据流，并决定是否[删除](https://docs.didit.me/zh/standalone-apis/bank-connection-delete.md)已存储的数据。
* **重复事件。** 以幂等方式处理每个事件：以事件 ID 作为键，并且偶尔会收到同一事件两次。
* **切勿信任浏览器。** 请通过 `bank.link.completed` 或 `GET /v3/bank/links/{id}/` 确认链接，而不要使用页面发送的链接 ID。

## 后续步骤

* [用于会计的持续银行数据流](https://docs.didit.me/zh/use-cases/bank-data-for-accounting.md)
* [沙盒](https://docs.didit.me/zh/core-technology/bank-verification/sandbox.md)：Didit Test Bank 会触发这些事件。


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