> ## 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のユーザーおよびビジネスエンティティのステータスやプロフィールが変わると、Webhookでリアルタイムに通知します。ペイロードのフィールド、署名、再試行について解説します。



エンティティWebhookのプロンプト
        プロンプトをクリップボードにコピー



      
      

\<pre>

\````# Goal — subscribe to entity-level webhooks and apply changes to my database

Entity webhooks fire whenever a User or Business entity changes its status or its profile data. Use them to keep your local mirror of Didit entities in sync.

\## Entity-level event catalog

\| `webhook_type` | Trigger |
\|---|---|
\| `user.status.updated` | User entity status changed (`ACTIVE` / `FLAGGED` / `BLOCKED`). Payload includes `previous_status`. |
\| `user.data.updated` | User entity profile / counters / metadata changed. Includes `changed_fields` and a `changes` map of `{previous, current}`. |
\| `business.status.updated` | Business entity status changed. Payload includes `previous_status`. |
\| `business.data.updated` | Business entity profile or aggregates changed. Includes `changed_fields` and `changes`. |

\`activity.created` is accepted in `subscribed_events` and by the Try Webhook tester, but Didit does not deliver it for live traffic. Do not build on it.

Session-level events (`status.updated`, `data.updated`) and transaction events (`transaction.created`, `transaction.status.updated`) live alongside but are separate — see /integration/webhooks for the full catalog.

\## Register a destination

\```bash
curl -X POST https://verification.didit.me/v3/webhook/destinations/ \
-H "x-api-key: $DIDIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"label": "Entity sync",
"url": "https://yourapp.com/webhooks/didit",
"webhook_version": "v3",
"subscribed_events": [
  "user.status.updated",
  "user.data.updated",
  "business.status.updated",
  "business.data.updated"
]
}'
\```

Persist the returned destination `secret_shared_key` — that's the HMAC signing key.

\## Payload shape

Entity payloads are flat: there is no `data` wrapper and no `event` key. Read `webhook_type`.

\```json
\{
"event_id": "7f3c2c1e-6a1d-4c36-9d8e-0d3b5f4e2a10",
"webhook_type": "user.status.updated",
"timestamp": 1776333600,
"created_at": 1776333594,
"application_id": "0c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
"environment": "live",
"vendor_user_id": "9c7d2a30-...",
"vendor_data": "user-42",
"status": "BLOCKED",
"previous_status": "ACTIVE"
}
\```

\`business.*` events use `vendor_business_id` instead of `vendor_user_id`.
\`user.data.updated` / `business.data.updated` payloads keep `status` and add `changed_fields` (array) and `changes` (`{field: {previous, current}}`). Use these to apply minimal diffs to your DB.

\## Verify the signature

Verify X-Signature-V2 (recommended): HMAC-SHA256 of the canonical JSON body with the destination `secret_shared_key`, then a constant-time compare, and reject an X-Timestamp older than 300 seconds. See /integration/webhooks for the signature headers and code samples. Respond `2xx` within **5 seconds**. On a 5xx, 404, timeout or connection failure Didit retries up to 2 times (about 1 minute, then about 4 minutes later); see /integration/webhooks#retry-policy.

\## Idempotency

Every delivery carries a unique `event_id`. De-dupe on it. Fallback compound key: `(application_id, webhook_type, vendor_data, timestamp)`.

\## Failure modes

\- Wrong `webhook_version` (e.g. v2) → singular fields and older event names; v3 is required for entity events plural-array contract.
\- Slow handler → retried; budget < 5s; do heavy work async.
\- Unknown event type → log and 200; new event types may be added.

\## Apply-decision pseudocode

\```ts
switch (event.webhook_type) {
case "user.status.updated":
await db.users.update({ vendor_data: event.vendor_data }, { status: event.status });
break;
case "user.data.updated":
for (const field of event.changed_fields) {
  await db.users.update({ vendor_data: event.vendor_data }, { [field]: event.changes[field].current });
}
break;
case "business.status.updated":
case "business.data.updated": /* same shape, businesses table, keyed by vendor_business_id */ break;
}
\```

\## Sources of truth

\- /integration/webhooks — destinations, signatures, retries, full event catalog
\- /management-api/webhook/create-destination — endpoint schema
\- /entities/users/operations — operations that emit user events
\- /entities/businesses/operations — operations that emit business events
\- /integration/integration-prompt — canonical end-to-end prompt````

\</pre>



      
      

貼り付け先

ユーザーエンティティまたは企業エンティティのステータスやプロフィールデータが変わるたびにWebhookが送信されるため、システム側でリアルタイムに対応できます。
エンティティWebhookは、プロフィールデータの同期、ブロックの他システムへの反映、後続のコンプライアンスフローのトリガーに利用できます。## イベントカタログ| イベント | トリガー |
| - | - |
| `user.status.updated` | ユーザーエンティティのステータスが変わったとき（`ACTIVE` ↔ `FLAGGED` ↔ `BLOCKED`） |
| `user.data.updated` | ユーザーエンティティのプロフィールフィールドが変わったとき（氏名、生年月日、顔写真、集計カウンター、メタデータ） |
| `business.status.updated` | 企業エンティティのステータスが変わったとき |
| `business.data.updated` | 企業エンティティのプロフィールフィールドが変わったとき（法人名、登記番号、国、カウンター） |> [!NOTE]
>
> `activity.created`は`subscribed_events`に指定でき、**Try Webhook**テスターの対象にもなっていますが、Diditは現在、本番トラフィックではこのイベントを配信していません。
> このイベントに基づくタイムラインのミラーリングを実装しないでください。Diditは、エンティティのフィールドを参照するセッション、取引、企業セッションのイベントも送信します。詳しくは次を参照してください。- [KYBのWebhook](https://docs.didit.me/ja/business-verification/webhooks.md)：企業セッションのイベント
- [トランザクションモニタリングのWebhook](https://docs.didit.me/ja/transaction-monitoring/webhooks.md)：取引のイベント
- [Webhookリファレンス](https://docs.didit.me/ja/integration/webhooks.md)：署名検証、再試行、送信先## ペイロードの形式エンティティWebhookはフラットな構造で、`data`ラッパーも`event`キーもありません。
イベントの振り分けには`webhook_type`を参照してください。```json theme={null}
{
  "event_id": "7f3c2c1e-6a1d-4c36-9d8e-0d3b5f4e2a10",
  "webhook_type": "user.status.updated",
  "timestamp": 1776333600,
  "created_at": 1776333594,
  "application_id": "0c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
  "environment": "live",
  "vendor_user_id": "9c7d2a30-2f98-4d4f-9d2d-1a7c4b1e5b6a",
  "vendor_data": "user-42",
  "status": "BLOCKED",
  "previous_status": "ACTIVE"
}
```| フィールド | 説明 |
| - | - |
| `vendor_user_id` / `vendor_business_id` | Diditが付与するエンティティの識別子です。`business.*`イベントでは`vendor_business_id`を使います。 |
| `vendor_data` | お客様側でのエンティティの識別子です。 |
| `status` | `ACTIVE`、`FLAGGED`、`BLOCKED`のいずれかです。 |
| `previous_status` | `*.status.updated`の場合のみ含まれます。 |
| `changed_fields`と`changes` | `*.data.updated`の場合のみ含まれます。 |
| `created_at` | エンティティが最後に更新された日時（Unix秒）です。 |
| `timestamp` | DiditがWebhookを送信した日時（Unix秒）です。 |### `user.status.updated` / `business.status.updated`ステータスが変わるたびに送信されます。
ペイロードには`status`と`previous_status`が含まれます。
ステータスが変わった理由は含まれないため、原因を知る必要がある場合はコンソールでエンティティを開いてください。### `user.data.updated` / `business.data.updated`プロフィールフィールドが変わったときに送信されます。
`changed_fields`には変更されたフィールドの一覧が、`changes`には各フィールドの`previous`と`current`の値が入ります。```json theme={null}
{
  "event_id": "5d1e8f9a-0c32-4b6a-a7b6-2b9d6f0a3c41",
  "webhook_type": "user.data.updated",
  "timestamp": 1776333700,
  "created_at": 1776333694,
  "application_id": "0c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
  "environment": "live",
  "vendor_user_id": "9c7d2a30-2f98-4d4f-9d2d-1a7c4b1e5b6a",
  "vendor_data": "user-42",
  "status": "ACTIVE",
  "changed_fields": ["full_name", "session_count"],
  "changes": {
    "full_name": { "previous": null, "current": "John Doe" },
    "session_count": { "previous": 2, "current": 3 }
  }
}
````changed_fields`に含まれる可能性のあるフィールドは次のとおりです。- ユーザー：`vendor_data`、`display_name`、`full_name`、`date_of_birth`、`metadata`、`portrait_image`、`issuing_states`、`approved_emails`、`approved_phones`、`features`、`session_count`、`approved_count`、`declined_count`、`in_review_count`、`first_session_at`、`last_session_at`。
- 企業：`vendor_data`、`display_name`、`metadata`、`legal_name`、`registration_number`、`country_code`、`session_count`、`approved_count`、`declined_count`、`in_review_count`、`features`、`first_session_at`、`last_session_at`。`changed_fields`と`changes`を使えば、変更されたフィールドだけを同期できます。## 配信、再試行、署名すべてのエンティティWebhookは、標準の配信仕様に従います。- **署名**：送信先の`secret_shared_key`を使い、HMAC-SHA256で`X-Signature-V2`ヘッダーに署名されます（推奨）。`X-Signature`と非推奨の`X-Signature-Simple`も、`X-Timestamp`とあわせて送信されます。
- **再試行**：エンドポイントが5xxまたは404を返した場合、タイムアウトした場合、接続に失敗した場合に、約1分後と約4分後の最大2回まで再試行されます。ポリシーの詳細は[Webhookリファレンス](https://docs.didit.me/ja/integration/webhooks.md#再試行ポリシー)を参照してください。
- **冪等性**：すべてのWebhookのペイロードには一意の`event_id`が含まれます。受信側で重複を排除してください。送信先の設定方法と署名検証のコードサンプルは、[Webhookリファレンス](https://docs.didit.me/ja/integration/webhooks.md)を参照してください。## サブスクライブManagement APIまたはBusiness Consoleから、Webhookの送信先でエンティティイベントをサブスクライブします。```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": "Entity sync",
    "url": "https://yourapp.com/webhooks/didit",
    "subscribed_events": [
      "user.status.updated",
      "user.data.updated",
      "business.status.updated",
      "business.data.updated"
    ]
  }'
```## 次のステップ> [card] [Webhookリファレンス](https://docs.didit.me/ja/integration/webhooks.md)
>
> 送信先、署名、再試行、検証。> [card] [送信先を作成](https://docs.didit.me/ja/management-api/webhook/create-destination.md)
>
> 新しいWebhookエンドポイントを登録します。> [card] [ユーザー操作](https://docs.didit.me/ja/entities/users/operations.md)
>
> ユーザーWebhookをトリガーする変更。


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