> ## 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 事件、Payload 与 HMAC 签名校验

> Didit 提供企业验证（KYB）Webhook 事件，涵盖会话与企业实体的触发条件、payload 结构和 HMAC 签名校验。每次检查低至 $2.00，无需签约。

Didit 的 KYB Webhook 会在企业验证（KYB）会话状态变化时，或审核员或公司登记更改其数据时，通知你的后端。
企业实体有各自的事件。
请通过 [Webhook 目标 API](https://docs.didit.me/zh/management-api/webhook/list-destinations.md) 或 Business Console 订阅你关心的事件。

## 事件目录

会话事件在用户会话和企业会话之间共用。
payload 中的 `session_kind` 字段会告诉你该事件属于哪一种会话。
实体级事件与会话级事件是分开的。

### 会话级事件

| 事件 | 触发时机 |
| - | - |
| `status.updated` | 会话状态发生变化。对于企业验证（KYB）会话，payload 中包含 `session_kind: "business"`。跟踪进度应关注此事件。 |
| `data.updated` | 审核员在控制台中编辑了公司登记数据，跳过或重新生成了关键人员，或公司登记报告了变更（在可使用[公司登记监控](https://docs.didit.me/zh/getting-started/kyb-registry-pricing.md)时）。`trigger` 字段说明具体原因。 |

申请人上传证件、提交关键人员或 AML 重新筛查完成时，不会发送 `data.updated`。
如需跟踪这些进度，请使用 `status.updated`，或[获取会话决策](https://docs.didit.me/zh/sessions-api/retrieve-session.md)。

### 企业实体事件

| 事件 | 触发时机 |
| - | - |
| `business.status.updated` | 关联的[企业实体](https://docs.didit.me/zh/entities/businesses/overview.md)状态发生变化（`ACTIVE` / `FLAGGED` / `BLOCKED`）。 |
| `business.data.updated` | 企业实体的资料字段或汇总计数器发生变化。 |

你可以在 Webhook 目标上订阅以上任意组合。
完整的企业/用户实体事件参考，请见[实体 Webhook](https://docs.didit.me/zh/entities/webhooks.md)。

## Payload 结构

会话 Webhook 使用扁平的 payload，没有 `data` 包装层。
信封、签名标头以及所有共用字段，都记录在 [Webhook 参考](https://docs.didit.me/zh/integration/webhooks.md#payload-结构)中。
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/zh/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/zh/sessions-api/retrieve-session) 相同，参见[响应结构](https://docs.didit.me/zh/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`。
请重新获取决策，以查看发生了哪些变化。
该 payload 没有 `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/zh/integration/webhooks.md#签名验证)列出了所有签名标头、签名密钥轮换的重叠期以及代码示例。

## 重试策略

* 返回 `5xx` 或 `404`、超时或连接失败时，最多重试 2 次，分别在约 1 分钟和约 4 分钟后进行，之后该投递会被丢弃。
* 其他 `4xx` 和 `3xx` 响应不会重试。
* 每次重试都保持相同的 `event_id`，因此请以它进行去重。
* 你可以从目标的投递日志中重新发送某次投递。完整策略见 [Webhook 参考](https://docs.didit.me/zh/integration/webhooks.md#重试策略)。

## 订阅

在 [Webhook 目标](https://docs.didit.me/zh/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/zh/integration/webhooks.md)
>
> 目标、签名、重试和常见模式。

> [card] [状态](https://docs.didit.me/zh/business-verification/statuses.md)
>
> 会话与功能状态参考。

> [card] [响应结构](https://docs.didit.me/zh/business-verification/response-schema.md)
>
> 解析 KYB 决策 payload。


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