Webhooks

Webhooks 让您可以订阅 k-ID Engine 中发生的事件，而不是轮询 API 来查看数据是否可用。

什么是 webhooks？

Webhooks 可用于多种目的，例如：

处理挑战完成结果
处理年龄验证结果
处理 k-ID 会话中的更改

设置 webhooks

Webhooks 在 Compliance Studio 中配置，通过指定当事件发生时 k-ID Engine 调用的 URL。URL 必须是安全的 HTTPS URL。k-ID Engine 向 URL 发送 POST 请求，其中包含包含事件数据的 JSON 负载。

信息

Webhooks 与单个产品关联。如果您有多个 k-ID 产品，可以为所有产品使用相同的端点，但重要的是要注意，您必须检索正确的产品特定 k-ID API 密钥来进行 API 调用（例如 /session/get）。

Webhooks 可以在 Compliance Studio 中产品的开发者设置部分配置。

Webhook Publisher Dashboard

Webhook 事件结构

发送到 webhook URL 的 JSON 负载包含以下字段：

eventType - 发生的事件类型。
data - 与事件关联的数据。

还发送带有事件类型的 X-Event-Type 标头。

验证 webhook 请求

Webhooks 通过公共互联网发送，因此验证请求来自 k-ID 很重要。这是通过使用配置的 webhook 密钥验证事件负载签名来完成的。

所有请求都包含以下标头：

X-Signature-Timestamp - 请求的时间戳，以 UNIX 纪元秒为单位。
X-Signature-Hmac-Sha256 - UTF-8 编码的时间戳和请求正文连接在一起的 HMAC SHA-256 键控哈希，使用 webhook 密钥作为键，编码为小写十六进制字符串。

如果签名无效，请求应被拒绝，状态代码为 401。具有已验证签名的 webhook 请求可以处理并接受，状态代码为 200。

验证代码示例

const crypto = require("crypto");

// 您的 webhook 密钥，在 [Compliance Studio](/compliance-studio/products/creating-new-product) 中配置。
const SECRET = "your-secret";

const timestamp = req.get("X-Signature-Timestamp");
const signature = req.get("X-Signature-Hmac-Sha256");
const body = req.rawBody; // 原始请求正文，作为字符串。

// 计算预期签名。
const hmac = crypto.createHmac("sha256", SECRET);
hmac.update(timestamp + body);
const expectedSignature = hmac.digest("hex");

// 安全地比较签名。
if (
  !crypto.timingSafeEqual(
    Buffer.from(signature, "hex"),
    Buffer.from(expectedSignature, "hex")
  )
) {
  return res.status(401).end("Unauthorized");
}

事件类型

事件类型	说明
`Challenge.StateChange`	当父母同意挑战更改状态时发出
`Verification.Result`	在验证尝试结果时发出
`Account.Delete`	当账户被删除时发出
`AgeAssurance.Result`	在年龄保证评估结果时发出（已弃用，由 `Verification.Result` 替换）
`ParentalConsent.Granted`	当授予父母同意时发出
`Session.ChangePermissions`	当会话权限被父母修改时发出
`Session.Delete`	当会话被删除时发出
`Test`	用于验证 webhook 是否正常工作

什么是 webhooks？​

设置 webhooks​

Webhook 事件结构​

验证 webhook 请求​

验证代码示例​

事件类型​