KYB Webhook API：イベント・ペイロード・署名検証

DiditのKYB Webhookは、法人確認セッションのステータスが変わったとき、またはレビュアーや法人登記によってデータが変更されたときに、バックエンドへ通知します。法人には専用のイベントがあります。必要なイベントは、Webhookの送信先APIまたはBusiness Consoleから購読してください。

イベント一覧

セッションイベントは、ユーザーセッションと企業セッションで共通です。ペイロードのsession_kindフィールドで、イベントがどちらの種類のセッションに関するものかがわかります。エンティティレベルのイベントは、セッションレベルのイベントとは別に扱われます。

セッションレベルのイベント

イベント	発生するタイミング
`status.updated`	セッションのステータスが変わったとき。法人確認 (KYB) セッションの場合、ペイロードには`session_kind: "business"`が含まれます。進捗を追跡するにはこのイベントを使用します。
`data.updated`	レビュアーがコンソールで登記データを編集したとき、主要人物をスキップまたは再生成したとき、または法人登記が変更を報告したとき (登記モニタリングが利用可能な場合)。どれに該当するかは`trigger`フィールドで示されます。

申請者が書類をアップロードしたときや主要人物を提出したとき、またはAMLの再スキャンが完了したときには、data.updatedは送信されません。これらの進捗を追跡するには、status.updatedを使用するか、セッションの判定を取得してください。

企業エンティティのイベント

イベント	発生するタイミング
`business.status.updated`	紐づく企業エンティティのステータスが変わったとき (`ACTIVE` / `FLAGGED` / `BLOCKED`)。
`business.data.updated`	企業エンティティのプロフィールフィールドまたは集計カウンターが変わったとき。

Webhookの送信先では、任意の組み合わせで購読できます。企業およびユーザーエンティティのイベントの完全なリファレンスは、エンティティWebhookを参照してください。

ペイロードの形式

セッションWebhookはフラットなペイロードを使用し、dataラッパーはありません。エンベロープ、署名ヘッダー、すべての共通フィールドはWebhookリファレンスに記載されています。 KYBセッションでは、次のフィールドが追加されます。

フィールド	型	説明
`session_kind`	`"business"`	汎用ハンドラーでKYCとKYBを分岐できます。
`business_session_id`	`uuid`	`session_id`と同じ値です。
`vendor_business_id`	string	企業エンティティに対する貴社の識別子です。セッション作成時に指定した場合に含まれます。
`status`	string	正確なラベルです。例: `"In Progress"`、`"Approved"`、`"Awaiting User"`。ステータスを参照してください。
`trigger`	string	任意。Webhookが発生した理由です。KYBの`data.updated`では、`"console_registry_edit"`、`"console_key_people_skip"`、`"console_key_people_regenerate"`、`"kyb_registry_change"`のいずれかです。
`decision`	object	`status`が`Approved`、`Declined`、`In Review`、`Abandoned`のいずれかの場合に含まれます。`GET /v3/session/{id}/decision/`と同じ形式です。レスポンススキーマを参照してください。
`resubmit_info`	object	`status`が`Resubmitted`の場合に含まれます。

KYBセッションの`status.updated`

{
  "event_id": "7f3c2c1e-6a1d-4c36-9d8e-0d3b5f4e2a10",
  "webhook_type": "status.updated",
  "session_id": "a1b2c3d4-5678-4abc-9def-1234567890ab",
  "business_session_id": "a1b2c3d4-5678-4abc-9def-1234567890ab",
  "session_kind": "business",
  "status": "Approved",
  "created_at": 1776515400,
  "timestamp": 1776515401,
  "application_id": "0c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
  "environment": "live",
  "workflow_id": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f7a8b9",
  "workflow_version": 3,
  "vendor_data": "biz-acme-001",
  "decision": { "...": "abbreviated KYB decision payload" }
}

decisionブロックには、registry_checks[]、key_people_checks[]、document_verifications[]、aml_screenings[]、その他のKYB用配列が含まれます。

KYBセッションの`data.updated`

data.updatedはstatus.updatedと同じフラットなエンベロープに加えて、発生理由を示すtriggerを含みます。セッションのステータスがApproved、Declined、In Review、Abandonedのいずれかの場合は、現在のdecisionも含まれます。何が変わったかを確認するには、判定を再取得してください。ペイロードにchanged_fieldsリストは含まれません。

`business.status.updated`と`business.data.updated`

エンティティイベントもフラットな形式です。 vendor_business_id、vendor_data、status (ACTIVE、FLAGGED、BLOCKEDのいずれか)、created_atを含みます。 business.status.updatedにはprevious_statusが追加されます。 business.data.updatedにはchanged_fieldsと、{ field: { previous, current } }形式のchangesマップが追加されます。

{
  "event_id": "2b9d6f0a-3c41-4e8b-b6a7-5d1e8f9a0c32",
  "webhook_type": "business.status.updated",
  "timestamp": 1776515401,
  "created_at": 1776515400,
  "application_id": "0c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
  "environment": "live",
  "vendor_business_id": "f7a9c1b2-4e6d-4f8a-9c5d-2a1b3c4d5e6f",
  "vendor_data": "biz-acme-001",
  "status": "FLAGGED",
  "previous_status": "ACTIVE"
}

署名検証

すべてのWebhookは、送信先の共有シークレットを使ってHMAC-SHA256で署名されます。生のリクエストボディをX-Signature-V2ヘッダー (推奨) で検証し、X-Timestampが300秒より古い配信は拒否してください。すべての署名ヘッダー、署名シークレットのローテーション時の重複期間、コードサンプルはWebhookリファレンスに記載されています。

再試行ポリシー

5xxまたは404のレスポンス、タイムアウト、接続失敗の場合は、約1分後と約4分後に最大2回まで再試行され、その後配信は破棄されます。
その他の4xxおよび3xxのレスポンスは再試行されません。
各再試行では同じevent_idが維持されるため、これを使って重複を排除してください。
送信先の配信ログから配信を再送できます。ポリシーの詳細はWebhookリファレンスを参照してください。

curl -X POST https://verification.didit.me/v3/webhook/destinations/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "KYB events",
    "url": "https://yourapp.com/webhooks/didit-kyb",
    "subscribed_events": [
      "status.updated",
      "data.updated",
      "business.status.updated",
      "business.data.updated"
    ]
  }'

企業セッションは、status.updatedおよびdata.updatedイベント内でsession_kind === "business"を確認することで、貴社側でフィルターしてください。

次のステップ

Webhookリファレンス

Webhookの送信先、署名、再試行、一般的なパターン。

ステータス

セッションと機能のステータスのリファレンス。

レスポンススキーマ

KYBの判定ペイロードの読み解き方。

はじめに

機能

企業プロフィール

リファレンス

コンソール

KYB Webhook API：イベント・ペイロード・署名検証

イベント一覧

セッションレベルのイベント

企業エンティティのイベント

ペイロードの形式

KYBセッションの`status.updated`

KYBセッションの`data.updated`

`business.status.updated`と`business.data.updated`

署名検証

再試行ポリシー

購読

次のステップ

Webhookリファレンス

ステータス

レスポンススキーマ

​イベント一覧

​セッションレベルのイベント

​企業エンティティのイベント

​ペイロードの形式

​KYBセッションのstatus.updated

​KYBセッションのdata.updated

​business.status.updatedとbusiness.data.updated

​署名検証

​再試行ポリシー

​購読

​次のステップ

Webhookリファレンス

ステータス

レスポンススキーマ

イベント一覧

セッションレベルのイベント

企業エンティティのイベント

ペイロードの形式

KYBセッションの`status.updated`

KYBセッションの`data.updated`

`business.status.updated`と`business.data.updated`

署名検証

再試行ポリシー

購読

次のステップ