通过 webhook 获取验证结果

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

Didit 支持团队撰写 · 更新于 2026年8月19日

Short answer

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

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

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

#设置步骤

  1. 进入 API & Webhooks

    在业务控制台中，打开你要接收事件的应用，然后进入 API & Webhooks。

  2. 添加一个目的地

    为它取一个标签，填入你端点的公开 HTTPS URL，并选择你想接收的事件（至少要包括会话状态变化）。

  3. 保存签名密钥

    目的地只会展示一次密钥。请保存它，你的服务器会用它来确认请求确实来自 Didit，而不是冒充者。 完整验证步骤参见签名验证。

  4. 测试它

    在同一个页面使用 Try Webhook，向你的端点发送一个完整的测试事件（已批准、已拒绝、审核中、KYB、实体和交易场景）。 这样你无需运行真实验证，也能验证你的集成是否正常。

Didit 控制台中的 webhook 目的地，展示已订阅事件和投递历史
  1. Add destination 用来注册 Didit 发送结果的目标地址。
  2. 在信任任何投递之前，先用这个签名密钥进行验证。
  3. 选择这个目的地要接收哪些事件。
  4. Test Webhook 会发送一个示例负载，方便你确认端点能正确接收。
每个目的地都有自己的已订阅事件、签名密钥和投递日志。

#你可以订阅的事件

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

事件触发时机
status.updatedKYC 或 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.updatedTravel Rule 交换的状态发生变化
Note

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

#你的端点应该做什么

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

#重试

在遇到 5xx、404、超时或连接失败时，Didit 会重试两次：

  • 第一次重试大约在初次失败后 1 分钟
  • 第二次重试大约在那之后再过 4 分钟

之后投递就会被丢弃。 每一次尝试都会单独记录在目的地的 Deliveries 标签页中，因此你可以看到确切发生了什么，而不用去猜测。

Important

五分钟内两次重试并不是一个持久化队列。 如果你的端点宕机一个小时，那些事件就永久丢失了。 请在启动时通过轮询决策接口，对账所有没有终态状态记录的会话，webhook 是快速通道，不是唯一通道。

#在防火墙或 WAF 之后

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

#还没有后端？

在你搭建后端之前，你仍然可以在控制台的验证部分手动查看结果，或者暂时使用无代码验证链接。

#下一步