# webhookで検証結果を取得する

Source: https://help.didit.me/ja/integration/webhooks-basics
Updated: 2026-10-12

Diditは検証のステータスが変わってもメールを送りません。その瞬間にバックエンドが知れるようwebhookを設定し、信頼する前に署名を検証してください。

webhookとは、何かが変化したときにDiditが自社のURLへ送るHTTPリクエストです。**開発者 → Webhook**の下に送信先を追加し、受け取りたいイベントを購読してください - **ワイルドカードはない**ので、すべて個別にリストしてください - 署名シークレットを保存し、何かを処理する前に必ず署名を検証してください。

[Video: webhookの概要 - Didit Academy](https://www.youtube.com/watch?v=fX03-WEu_EI&t=192)

Diditは、セッションが**In Review**や**Declined**に移ったときにメールを送信しません。コンソールを更新することなくステータスの変化をその瞬間に知るには、webhookを設定してください。これは、Diditが自動的に更新を送信する、自社サーバー上のURLです。

webhookは**推奨される**連携パターンです。判定エンドポイントをポーリングする方法もフォールバックとしては機能しますが、より遅く、リクエスト数も増え、webhookでしか配信されないイベント（レビュアーによるデータ編集、トランザクションのステータス変化、エンティティレベルの変化）を取りこぼします。

## 設定方法

1. **開発者 → Webhook**

   対象のアプリケーションとLiveまたはSandbox環境を選び、開発者、Webhookの順に開きます。

2. **エンドポイントを追加**

   エンドポイントを追加を押し、HTTPS URL、名前、購読するイベントを設定します。古い連携を保守する場合以外は推奨のv3を使い、確認して保存します。

3. **署名シークレットを保存する**

   各エンドポイントには個別の署名シークレットがあります。表示を押して本人確認すると表示され、60秒以内に再び隠れます。サーバー設定に保存してください。表示が無効な場合はサポートに連絡します。 [開発者 → Webhook](https://docs.didit.me/integration/webhooks#signature-verification).

4. **テストイベントを送信**

   署名付きのテストイベントで、実際の本人確認を実行せずにエンドポイント、署名、処理を確認します。

![購読イベントと配信履歴を表示するDiditコンソールのwebhook送信先](https://help.didit.me/screenshots/webhooks-light.webp)

*各送信先には、それぞれ独自の購読イベント、署名シークレット、配信ログがあります。*

## 購読できるイベント

**ワイルドカードはありません** - 欲しいイベントファミリーはすべてリストしてください。複数の送信先に分けることも問題なく、むしろすっきりすることが多いです。

| イベント | 発火するタイミング |
|---|---|
| `status.updated` | KYCまたはKYBセッションのステータスが変化したとき。ほぼ間違いなく欲しいイベント |
| `data.updated` | 作成後に検証データが編集されたとき - レビュアーによるフィールドの修正など |
| `user.status.updated` | 統合ユーザーがACTIVE、FLAGGED、BLOCKEDの間で移動したとき |
| `user.data.updated` | 統合ユーザーのプロフィール、カウンター、識別子が変化したとき |
| `business.status.updated` | 統合ビジネスのステータスが変化したとき |
| `business.data.updated` | 統合ビジネスのデータが変化したとき |
| `transaction.created` | トランザクションが作成され、初期判定が準備できたとき |
| `transaction.status.updated` | トランザクションのステータスがその後変化したとき |
| `travel_rule.status.updated` | Travel Rule交換のステータスが変化したとき |

> **Note:** `session.status.updated`や`kyc.completed`というものは存在しません。このリストにない名前を購読していた場合、何も届かず、それは配信失敗とまったく同じように見えます。まず名前を確認してください。

## 自社エンドポイントがすべきこと

- **何よりもまず署名を検証する。** HMACは**生の**リクエスト本文で計算してください - パースしたJSONを再シリアライズしたものではいけません。再文字列化するとバイト列が変わり、署名が一致しなくなります。比較には定数時間比較を使ってください。
- **すばやく2xxを返す。** 重い処理は応答した後に非同期で行ってください。
- **冪等にする。** イベントID、あるいはセッションID＋ステータス＋webhookタイプをキーにしてください。リトライや重複は発生します。
- **気にかけているすべてのステータスを処理する。** オンボーディングのずっと後に届くものも含みます。承認済みのセッションは、[AML継続モニタリング](https://help.didit.me/ja/aml-screening/ongoing-monitoring)によって後からIn Reviewに移ることがあります。
- **HTTPSのみ。** 平文HTTPのエンドポイントには対応していません。

## リトライ

5xxまたは404の応答には約1分後、さらに4分後の2回再試行します。5秒のタイムアウトや接続失敗は自動再試行されません。修正後は配信一覧から再送できます。最終的な失敗ではアラートが表示されます。

> **Warning:** すべてのWebhookが届くとは限りません。障害後は再送するか、結果を受け取っていないセッションの決定をAPIで取得してください。

## ファイアウォールやWAFの背後にある場合

Diditは静的IPの**18.203.201.92**から、`DiditWebhook/2.0`というユーザーエージェントで配信します。自社のエッジが未知のクライアントをブロックする場合 - 例えばCloudflareのデフォルトの姿勢など - 受信ホスト名についてそのIPを許可してください。さもないと配信は自社のコードに届く前に失敗します。

## まだバックエンドがない場合

構築している間は、コンソールの**Verifications**セクションで結果を手動で監視することもできますし、その間だけ[ノーコードの検証リンク](https://help.didit.me/ja/integration/integration-options)を使うこともできます。

## 次のステップ

- webhookが届かないとき: [webhookが一向に届かないとき](https://help.didit.me/ja/integration/webhook-troubleshooting)
- 届いた各ステータスの意味を理解する: [各セッションステータスの意味](https://help.didit.me/ja/verification-sessions/session-statuses)
- 署名検証のコードサンプルを含む完全な技術リファレンス: [Webhooks](https://docs.didit.me/integration/webhooks)