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

简短回答

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

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

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

#设置步骤

  1. 开发者 → Webhooks

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

  2. 添加端点

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

  3. 保存签名密钥

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

  4. 发送测试事件

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

Didit 控制台中的 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 交换的状态发生变化
注意

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

#你的端点应该做什么

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

#重试

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

重要

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

#在防火墙或 WAF 之后

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

#还没有后端？

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

#下一步

还没解决？和真人聊聊。

请附上你的组织 ID 以及你要咨询的会话 ID。

联系支持团队