webhookで検証結果を取得する

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

執筆: Didit サポート · 更新日: 2026年8月19日

Short answer

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

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

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

#設定方法

  1. API & Webhooksを開く

    Business Consoleで、イベントを受け取りたいアプリケーションを開き、API & Webhooksに移動します。

  2. 送信先を追加する

    ラベル、自社エンドポイントの公開HTTPS URLを指定し、受け取りたいイベントを選びます - 最低限、セッションステータスの変化は含めてください。

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

    送信先はシークレットを一度だけ表示します。保存してください。自社サーバーは、リクエストがなりすましではなく本当にDiditから来たものであることを確認するためにこれを使います。完全な検証手順: 署名検証。

  4. テストする

    同じページのTry Webhookを使って、完全な形のテストイベント - 承認、拒否、審査中、KYB、エンティティ、トランザクションの各シナリオ - を自社エンドポイントに送信します。実際の検証を実行しなくてもこの方法で連携を検証できます。

購読イベントと配信履歴を表示するDiditコンソールのwebhook送信先
  1. Add destinationで、Diditが結果を送信するURLを登録します。
  2. 信頼する前に、必ずこの署名シークレットに対して各配信を検証してください。
  3. その送信先が受け取るイベントを選びます。
  4. Test Webhookはサンプルのペイロードを送信し、自社エンドポイントが受け入れられるか確認できます。
各送信先には、それぞれ独自の購読イベント、署名シークレット、配信ログがあります。

#購読できるイベント

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

イベント発火するタイミング
status.updatedKYCまたは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.updatedTravel Rule交換のステータスが変化したとき
Note

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

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

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

#リトライ

5xx、404、タイムアウト、または接続失敗の場合、Diditは2回リトライします。

  • 最初のリトライは、最初の失敗からおよそ1分後
  • 2回目のリトライは、その約4分後

それ以降、配信は打ち切られます。すべての試行は送信先のDeliveriesタブに個別に記録されるため、推測ではなく実際に何が起きたかを確認できます。

Important

5分間に2回のリトライは、耐久性のあるキューではありません。自社エンドポイントが1時間ダウンしていた場合、それらのイベントは失われます。起動時に、確定ステータスを持たないセッションについて判定エンドポイントをポーリングすることで整合性を取ってください - webhookは高速な経路であって、唯一の経路ではありません。

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

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

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

構築している間は、コンソールのVerificationsセクションで結果を手動で監視することもできますし、その間だけノーコードの検証リンクを使うこともできます。

#次のステップ