> ## 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を送信します。
銀行Webhookは、他のDidit Webhookと同じエンベロープ、署名、再試行の仕組みを使用し、IDとステータスのみを含みます。内容を読むには、オブジェクトを取得してください。

> [!NOTE]
>
> 銀行Webhookのイベントは、本番環境とサンドボックスのアプリケーションに対して送信されます。
> 他のイベントと同様に、Webhookの送信先ごとに、その送信先のイベントフィルターでイベントを選択してください。
> エンベロープ、署名ヘッダー、再試行については、[Webhook](https://docs.didit.me/ja/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/ja/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/ja/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/ja/standalone-apis/bank-connection-delete.md)するかどうかを判断してください。
* **重複。** すべてのイベントを冪等に扱ってください。イベントIDをキーにし、同じイベントが時々2回届く場合があることを想定してください。
* **ブラウザを信頼しないでください。** リンクの確認は、ページから送られたリンクIDではなく、`bank.link.completed` または `GET /v3/bank/links/{id}/` を使って行ってください。

## 次のステップ

* [会計向けの継続的な銀行フィード](https://docs.didit.me/ja/use-cases/bank-data-for-accounting.md)
* [サンドボックス](https://docs.didit.me/ja/core-technology/bank-verification/sandbox.md): Didit Test Bank がこれらのイベントを発生させます。


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