Webhooks 概述
Webhooks 通知您的服务器有关 k-ID 中的重要事件，例如挑战状态更改和验证结果。在 Compliance Studio 的开发者设置中为每个产品配置 Webhook URL 和密钥。
负载包括 eventType 和 data 对象。有关负载架构，请参阅事件类型。
事件类型
| 事件类型 | 说明 |
|---|---|
Challenge.StateChange | 当父母同意挑战更改状态时发出 |
Verification.Result | 在验证尝试结果时发出 |
Verification.Revoke | 当先前通过的验证被撤销时发出 |
Account.Delete | 当账户被删除时发出 |
AgeAssurance.Result | 在年龄保证评估结果时发出（已弃用，已替换为 Verification.Result） |
Session.ChangePermissions | 当父母修改会话权限时发出 |
Session.Delete | 当会话被删除时发出 |
Test | 用于验证 Webhook 是否正常工作 |
签名验证
使用配置的 Webhook 密钥验证 Webhook 请求。
标头
每个请求发送的标头：
X-Signature-Timestamp: UNIX 纪元秒数X-Signature-Hmac-Sha256: (timestamp + raw body) 的 HMAC SHA-256，使用 Webhook 密钥作为密钥，十六进制编码（小写）
预期行为
- 对于有效签名返回
200 - 对于无效签名返回
401
有关实现详细信息，请参阅 验证 Webhook 请求。
投递、重试与恢复
投递保证
k-ID 以至少一次（at-least-once）保证投递 Webhook 事件。您的端点可能会多次收到同一事件，因此请将处理程序设计为幂等的。使用 data.id 字段（验证或挑战 ID）来对已处理的事件进行去重。
重试策略
当您的端点返回非 200 状态码或请求超时时，k-ID 会重试 2 次：
| 尝试 | 距上一次尝试的延迟 |
|---|---|
| 第1次重试 | 5 秒 |
| 第2次重试 | 10 秒 |
在初始尝试加两次重试（共三次尝试）之后，k-ID 将停止投递该事件。
处理错过的 Webhook
如果您的服务器宕机或 Webhook 未成功投递，可以使用启动流程时保存的 ID 从服务器轮询相关的状态端点来恢复：
- 验证：使用验证 ID 调用
GET /age-verification/get-status - 挑战：使用挑战 ID 调用
GET /challenge/get-status
推荐模式
始终保存您在启动流程时收到的验证或挑战 ID。如果您的 Webhook 处理程序在预期时间内未收到结果，请调用相应的 get-status 端点以获取当前状态。这种重定向→轮询的模式确保即使所有 Webhook 投递失败，您也不会错过任何结果。
幂等性
Webhook 事件是幂等的。同一事件可能会被多次投递，例如当网络问题导致投递状态不明确时。在对事件执行操作之前，请始终检查是否已经处理过该事件。一种简单的方法是跟踪已处理的事件 ID（data.id 字段）并跳过重复项。