Webhooks
Webhook 是一种可以在事件发生时订阅 k-ID 引擎事件的机制，而无需轮询 API 来检查数据是否可用。
Webhook 可用于多种目的，例如：
1 处理成人验证结果 2 处理年龄保证结果 3 处理挑战状态变更
配置 Webhook
可以在厂商门户中配置 Webhook，通过指定一个 URL，当事件发生时，k-ID 引擎将调用该 URL。URL 必须是一个安全的 HTTPS URL。k-ID 引擎会向该 URL 发送带有事件数据的 JSON 格式 POST 请求。
Webhook 可在选定产品的 开发者设置 页面中配置。访问路径为 /products/[productId]/developer。
Webhook 配置页面
在 开发者设置 页面中的 Webhook 部分，可以为您的应 用程序配置 HTTPS URL，当发生特定事件时，k-ID 将调用这些 URL。通过输入所需的 Webhook URL 并点击 保存，您的配置将更新到系统中。更改将根据当前设置自动应用到适当的环境（测试模式或在线模式）。
这确保了无论您是在测试还是生产环境中，事件通知都能正确、安全地路由到您的应用程序。
注意：保存按钮与 推送到测试 和 发布到在线 按钮不同。保存和更新 Webhook 不会直接影响用户，但使用 推送到测试 或 发布到在线 所做的更改可能会影响整体用户体验，并可能需要 k-ID 团队的审查后才能生效。
此外，还有一个 测试 Webhook 按钮 
，允许您验证端点是否设置正确，无论是否使用密钥。您可以在文档中找到有关验证 Webhook 请求的更多详细信息。该按钮会模拟一个测试事件，参考文档中的测试事件部分。
Webhook 事件结构
发送到 Webhook URL 的 JSON 负载将包含以下字段：
eventType- 发生的事件类型。data- 与事件相关的数据。
一个 X-Event-Type 标头也会随事件类型一起发送。
验证 Webhook 请求
Webhook 通过公共互联网发送，因此验证请求来自 k-ID 是很重要的。这可以通过使用配置的 Webhook 密钥验证事件负载签名来完成。
所有请求将包含以下头部：
X-Signature-Timestamp- 请求的时间戳，以 Unix epoch 秒为单位。X-Signature-SHA256- Webhook 密钥、时间戳和请求正文的 SHA-256 哈希值，编码为十六进制字符串。
如果签名无效，请使用 401 状态码拒绝请求。
示例代码
// 在厂商门户中配置的 Webhook 密钥。
const SECRET = "your-secret";
const timestamp = req.get("X-Signature-Timestamp");
const signature = req.get("X-Signature-SHA256");
const body = req.rawBody; // 原始请求正文，字符串形式。
// 使用您喜欢的加密库计算预期签名。
const expectedSignature = crypto
.createHash("sha256")
.update(SECRET + timestamp + req.rawBody)
.digest("hex");
const isVerified = crypto.timingSafeEqual(
Buffer.from(signature),
Buffer.from(expectedSignature)
);
if (!isVerified) {
return res.status(401).end("Invalid signature");
}
Webhook 事件类型
以下是可用的事件类型
TestChallenge.StateChangeSession.ChangePermissionsSession.DeleteVerification.ResultAdultVerification.ResultAgeAssurance.Result
Test测试
此事件类型用于验证 Webhook 是否正常工作。Webhook 接收器应处理此事件。
示例负载：
{
"eventType": "Test",
"data": {
"id": "12345678-1234-1234-1234-123456789abc"
}
}
Challenge State Change 挑战状态变更
属性：
id- 挑战 ID。productId- 产品 ID。status- 可以是PASS,FAIL, 或IN_PROGRESS.sessionId(可选）- 如果状态是PASS，则返回会话 ID。approverEmail（可选）- 如果状态是PASS，则返回批准者的电子邮件。
示例负载：
{
"eventType": "Challenge.StateChange",
"data": {
"id": "683409f1-2930-4132-89ad-827462eed9af",
"productId": 42,
"status": "PASS",
"sessionId": "0ad1641f-c154-4cc2-8bb2-74dbd0de7723",
"approverEmail": "user@example.com"
}
}
Session Change Permissions 会话权限变更
仅当家长在 k-ID 家庭门户中直接修改权限时，才会将此类型的事件发送到您的 Webhook 接收器。如果玩家因生日进入不同年龄类别，或超过其司法管辖区的年龄门槛以允许访问更多功能，游戏必须调用/session/get 以接收更改后的权限。
属性：
id- 会话 ID。productId- 产品 ID。
示例负载：
{
"eventType": "Session.ChangePermissions",
"data": {
"id": "78c299b2-5c33-4bde-84fe-8fc950fc7a96",
"productId": 42
}
}
Session Delete 会话删除
属性：
id- 会话 ID。productId- 产品 ID。
示例负载：
{
"eventType": "Session.Delete",
"data": {
"id": "2d064cf7-0726-4193-b19a-8bd387937e60",
"productId": 42
}
}
Verification Result 验证结果
属性：
id- 唯一的验证 ID。status- 可以是PASS、FAIL或INCONCLUSIVE。ageCategory（可选）- 估算的年龄类别，可以是adult（成人）、digital-youth（数字青年）或digital-minor（数字未成年人）。仅当status为PASS时设置。method（可选）- 使用的验证方法，可以是id-document（身份证件）、credit-card（信用卡）或age-estimation（年龄估算）。仅当status为PASS时设置。age（可选）- 年龄详情。仅当status为PASS且验证场景配置为返回年龄时设置。
age 属性：
low- 估算年龄的下限。对于硬性年龄验证方法（例如身份证件检查），此值为确切年龄。high- 估算年龄的上限。对于硬性年龄验证方法（例如身份证件检查），此值为确切年龄。confidence- 表示估算年龄范围可信度的 0 到 1 之间的浮点数。对于硬性年龄验证方法，此值为 1。
示例负载：
{
"eventType": "Verification.Result",
"data": {
"id": "5a58e98a-e477-484b-b36a-3857ea9daaba",
"status": "PASS",
"ageCategory": "adult",
"method": "id-document",
"age": {
"low": 25,
"high": 25,
"confidence": 1
}
}
}
Adult Verification Result 成人验证结果
属性：
id- 唯一的验证 ID。status- 可以是PASS、FAIL或INCONCLUSIVE。ageRange（可选）- 关于估算年龄范围的详细信息。
ageRange 属性：
minAge- 估算的最小年龄。maxAge- 估算的最大年龄。confidence- 表示估算年龄范围可信度的 0 到 1 之间的数字。
示例负载：
{
"eventType": "AdultVerification.Result",
"data": {
"id": "5a58e98a-e477-484b-b36a-3857ea9daaba",
"status": "PASS"
}
}
Age Assurance Result 成人验证结果
属性：
id- 唯一的验证 ID。status- 可以是PASS、FAIL或INCONCLUSIVE。ageRange（可选）- 关于估算年龄范围的详细信息。
ageRange 属性：
minAge- 估算的最小年龄。maxAge- 估算的最大年龄。confidence- 表示估算年龄范围可信度的 0 到 1 之间的数字。
示例负载：
{
"eventType": "AgeAssurance.Result",
"data": {
"id": "5a58e98a-e477-484b-b36a-3857ea9daaba",
"status": "PASS",
"ageRange": {
"minAge": 18,
"maxAge": 25,
"confidence": 0.8
}
}
}