> ## 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.

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

> DiditのKYB Webhookは、セッションと企業エンティティのイベントを、トリガー、ペイロードスキーマ、HMAC署名検証とともに通知します。チェック1件あたり$2.00から、契約不要。

DiditのKYB Webhookは、法人確認セッションのステータスが変わったとき、またはレビュアーや法人登記によってデータが変更されたときに、バックエンドへ通知します。
法人には専用のイベントがあります。
必要なイベントは、[Webhookの送信先API](https://docs.didit.me/ja/management-api/webhook/list-destinations.md)またはBusiness Consoleから購読してください。

## イベント一覧

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

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

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

申請者が書類をアップロードしたときや主要人物を提出したとき、またはAMLの再スキャンが完了したときには、`data.updated`は送信されません。
これらの進捗を追跡するには、`status.updated`を使用するか、[セッションの判定を取得](https://docs.didit.me/ja/sessions-api/retrieve-session.md)してください。

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

| イベント | 発生するタイミング |
| - | - |
| `business.status.updated` | 紐づく[企業エンティティ](https://docs.didit.me/ja/entities/businesses/overview.md)のステータスが変わったとき (`ACTIVE` / `FLAGGED` / `BLOCKED`)。 |
| `business.data.updated` | 企業エンティティのプロフィールフィールドまたは集計カウンターが変わったとき。 |

Webhookの送信先では、任意の組み合わせで購読できます。
企業およびユーザーエンティティのイベントの完全なリファレンスは、[エンティティWebhook](https://docs.didit.me/ja/entities/webhooks.md)を参照してください。

## ペイロードの形式

セッションWebhookはフラットなペイロードを使用し、`data`ラッパーはありません。
エンベロープ、署名ヘッダー、すべての共通フィールドは[Webhookリファレンス](https://docs.didit.me/ja/integration/webhooks.md#ペイロードの構造)に記載されています。
KYBセッションでは、次のフィールドが追加されます。

| フィールド | 型 | 説明 |
| - | - | - |
| `session_kind` | `"business"` | 汎用ハンドラーでKYCとKYBを分岐できます。 |
| `business_session_id` | `uuid` | `session_id`と同じ値です。 |
| `vendor_business_id` | string | 企業エンティティに対する貴社の識別子です。セッション作成時に指定した場合に含まれます。 |
| `status` | string | 正確なラベルです。例: `"In Progress"`、`"Approved"`、`"Awaiting User"`。[ステータス](https://docs.didit.me/ja/business-verification/statuses.md)を参照してください。 |
| `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/`](https://docs.didit.me/ja/sessions-api/retrieve-session)と同じ形式です。[レスポンススキーマ](https://docs.didit.me/ja/business-verification/response-schema.md)を参照してください。 |
| `resubmit_info` | object | `status`が`Resubmitted`の場合に含まれます。 |

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

```json theme={null}
{
  "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`マップが追加されます。

```json theme={null}
{
  "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リファレンス](https://docs.didit.me/ja/integration/webhooks.md#署名検証)に記載されています。

## 再試行ポリシー

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

## 購読

必要なイベントを[Webhookの送信先](https://docs.didit.me/ja/management-api/webhook/create-destination.md)で購読します。

```bash theme={null}
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"`を確認することで、貴社側でフィルターしてください。

## 次のステップ

> [card] [Webhookリファレンス](https://docs.didit.me/ja/integration/webhooks.md)
>
> Webhookの送信先、署名、再試行、一般的なパターン。

> [card] [ステータス](https://docs.didit.me/ja/business-verification/statuses.md)
>
> セッションと機能のステータスのリファレンス。

> [card] [レスポンススキーマ](https://docs.didit.me/ja/business-verification/response-schema.md)
>
> KYBの判定ペイロードの読み解き方。


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