# 通过 webhook 获取验证结果

Source: https://help.didit.me/zh/integration/webhooks-basics
Updated: 2026-10-12

Didit 不会在验证状态变化时给你发邮件，请设置一个 webhook，让你的后端在事件发生的那一刻就能收到通知，并在处理之前先验证签名。

webhook 是 Didit 在有变化发生时发送到你的 URL 的一次 HTTP 请求。
在 **开发者 → Webhooks** 下添加一个目的地，订阅你需要的事件（这里**没有通配符**，需要逐一列出），保存签名密钥，并在处理任何内容之前先验证签名。

[Video: Webhook 概览 - Didit Academy](https://www.youtube.com/watch?v=fX03-WEu_EI&t=192)

当会话变为**审核中**或**已拒绝**时，Didit 不会给你发邮件。
如果你想在状态变化的那一刻就知道，而不用刷新控制台，就要设置一个 webhook：一个在你服务器上的 URL，Didit 会自动把更新发送到那里。

webhook 是**推荐**的集成方式。
轮询决策接口可以作为兜底方案，但速度更慢、消耗更多请求，而且会错过一些只通过 webhook 投递的事件，例如审核人员做出的数据修改、交易状态变化，以及实体级别的变化。

## 设置步骤

1. **开发者 → Webhooks**

   打开正确的应用和 Live 或 Sandbox 环境，然后进入开发者和 Webhooks。

2. **添加端点**

   点击添加端点，输入 HTTPS URL 和名称并选择事件。除非维护旧集成，否则保留推荐的 v3 版本，然后检查并确认。

3. **保存签名密钥**

   每个端点都有独立的签名密钥，默认隐藏。点击显示并确认身份后可查看，60 秒内会再次隐藏。保存在服务器配置中；若显示按钮不可用，请联系支持团队。 [开发者 → Webhooks](https://docs.didit.me/integration/webhooks#signature-verification).

4. **发送测试事件**

   发送已签名的测试事件，无需真实验证即可检查端点、签名和处理程序。

![Didit 控制台中的 webhook 目的地，展示已订阅事件和投递历史](https://help.didit.me/screenshots/webhooks-light.webp)

*每个目的地都有自己的已订阅事件、签名密钥和投递日志。*

## 你可以订阅的事件

这里**没有通配符**，需要列出你想要的每一个事件系列。
把它们分散到多个目的地也是可以的，通常还更清晰。

| 事件 | 触发时机 |
|---|---|
| `status.updated` | KYC 或 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.updated` | Travel Rule 交换的状态发生变化 |

> **Note:** 不存在 `session.status.updated` 或 `kyc.completed` 这样的事件。
> 如果你订阅了一个不在此列表中的名称，你会什么都收不到，而且看起来会和投递失败一模一样。
> 请先核对名称。

## 你的端点应该做什么

- **先验证签名，再做其他任何事。** 对**原始**请求体做 HMAC，永远不要用重新序列化后的解析结果，因为重新字符串化会改变字节内容，签名就会对不上。使用恒定时间比较。
- **快速返回 2xx。** 把耗时的处理放到响应之后异步执行。
- **保证幂等。** 用事件 ID，或用会话 ID 加状态加 webhook 类型作为键。重试和重复是会发生的。
- **处理你关心的每一种状态**，包括那些在入网流程很久之后才到达的状态，例如一个已批准的会话，可能之后通过[持续 AML 监控](https://help.didit.me/zh/aml-screening/ongoing-monitoring)变为审核中。
- **仅支持 HTTPS。** 不支持纯 HTTP 端点。

## 重试

收到 5xx 或 404 响应时，Didit 会在约一分钟后重试，再过四分钟重试一次。超过 5 秒的超时或连接失败不会自动重试。修复后在投递列表使用重新发送；最终失败会产生提醒。

> **Warning:** 不要假设每个 webhook 都一定送达。服务中断后，重新发送投递，或通过 API 查询尚未收到结果的会话。

## 在防火墙或 WAF 之后

Didit 从静态 IP **18.203.201.92** 发送请求，User-Agent 为 `DiditWebhook/2.0`。
如果你的边界会拦截未知客户端（例如 Cloudflare 的默认策略），请为接收主机名放行这个 IP，否则投递会在到达你的代码之前就失败。

## 还没有后端？

在你搭建后端之前，你仍然可以在控制台的**验证**部分手动查看结果，或者暂时使用[无代码验证链接](https://help.didit.me/zh/integration/integration-options)。

## 下一步

- 当 webhook 没有送达时：[当 webhook 一直没有送达](https://help.didit.me/zh/integration/webhook-troubleshooting)
- 了解每种状态到达后代表什么：[每种会话状态的含义](https://help.didit.me/zh/verification-sessions/session-statuses)
- 完整技术参考，包括签名验证代码示例：[Webhooks](https://docs.didit.me/integration/webhooks)