Configure the PV service webhook

如何配置从KWS接收成功验证事件的家长验证服务网钩。

阅读时间4分钟

介绍

当家长使用家长验证服务成功验证其身份时,KWS通过网钩调用发送 parent-verified 事件来通知你的系统。

如果你要配置网钩(webhook),你需要:

  • 提供KWS向其发送网钩的URL
  • 使用KWS在 家长验证(Parent Verification) 选项卡产品集成细节中提供的 网钩密钥代码(Webhook secret code) 生成签名。密钥代码用于签署负载,确认网钩是来自KWS的真实调用。

注意:你的测试环境和生产环境都带有自己独特的网钩密钥代码。

设置你的网钩URL

  1. 家长验证(Parent Verification) 选项卡中,输入 验证成功的网钩URL(Successful verification webhook URL) 。这是KWS发送网钩确认验证成功的位置。

重要提示:

  • 不要在网钩URL中包含容易被攻击者操纵的信息(例如,可以轻松迭代的数字ID)。
  • 不要在你的URL中包含特殊字符。
  1. 点击 发布到测试(Publish to Test)

使用密钥代码生成你的签名

点击 发布到测试(Publish to Test) 后,家长验证(Parent Verification) 选项卡会显示 网钩密钥代码(Webhook secret code)

密钥代码

点击查看大图。

示例

此示例展示了如何使用密钥代码创建签名。

KWS会向你发送网钩。网钩调用是HTTPS POST,它具有封装事件特定负载的通用结构:

POST https://www.yourdomain.com/your-webhook-endpoint
x-kws-signature: t=1621535329,v1=f7bc83f430538424b13298e6aa6fb143ef4d59a14946175997479dbc2d1a3cd8
Body
{
"name": "webhook-name",
"time": "ISO8601 timestamp",
"orgId": "uuid",
"productId": "uuid" | null,
"environmentId": "uuid" | null,
"payload": { ... type-specific payload ... }
}

POST调用的头文件具有以下结构:

x-kws-signature: t=<timestamp>,v1=<signature>[,v1=<signature>]

其中<signature>通过HMAC_SHA256使用头文件中的时间戳值、在 家长验证(Parent Verification) 选项卡的产品集成细节中显示的 网钩密钥代码(Webhook secret code) 以及POST正文生成。

const timestamp = /* extracted value of 't=' from the header */;
const body = /* raw request body as UTF-8 string */;
const secretKey = /* secret key, as provided in the Developer Portal */;
const signature = crypto
.createHmac('sha256', secretKey)
.update('${timestamp}.${body}')
.digest('hex');

在你的产品方面,你需要使用上述代码和时间戳、网钩密钥代码 和POST正文创建相同的签名。如果你创建的签名与我们在网钩调用的头文件中传递给你的v1签名匹配,那么你可以确认网钩是由我们发送的。

通过你的Web服务器/Web应用程序显示公共端点(类似于你构建其他API端点的方式)。此端点采用下述POST正文,并验证签名头文件。

注意:使用原始POST正文很重要。不要尝试解析和重新字符串化JSON,因为这可能会由于JSON库实现中的不一致而导致签名不匹配。

POST正文结构

POST https://www.yourdomain.com/your-webhook-endpoint
x-kws-signature: t=<timestamp>,v1=<signature>[,v1=<signature>]
Body
{
"name": "webhook-name",
"time": "ISO8601 timestamp",
"orgId": "uuid",
"productId": "uuid" | null,
"environmentId": "uuid" | null,
"payload": { ... type-specific payload ... }
}

签名

要确认网钩确实来自KWS,请将你生成的v1签名与你从KWS收到的网钩调用的头文件中的v1签名进行比较。如果签名匹配,你可以确认调用来自KWS。

签名是十六进制格式(小写)的HMAC_SHA256哈希,其中密钥是我们在 家长验证(Parent Verification) 选项卡中为你提供的 网钩密钥代码(Webhook secret code)

签名通过以下格式的x-kws-signature头文件发送:

x-kws-signature: t=<timestamp>,v1=<signature>[,v1=<signature>]

注意:目前仅包含一个v1签名,但在以下情况下,头文件可能包含多个签名:

  • 支持签名密钥轮换(将在过渡期内为先前和当前密钥发送签名)。
  • 签名算法发生变化(v2签名将在过渡期内与v1签名一起发送)。

生成v1签名的算法是包含在签名头文件中的时间戳的HMAC_SHA256,后跟句点('.'),然后是原始请求正文。使用网钩的密钥代码初始化HMAC。

例如:

const timestamp = /* extracted value of 't=' from the header */;
const body = /* raw request body as UTF-8 string */;
const secretKey = /* the webhook secret code from the Parent Verification tab. */;
const signature = crypto
.createHmac('sha256', secretKey)
.update(`${timestamp}.${body}`)
.digest('hex');

注意:当请求URL可能被修改时,系统会故意不将网钩URL包含在签名算法中,以便在反向代理/负载平衡器等背后的服务中更轻松地进行签名验证。

网钩重试行为

网钩重试行为取决于你的服务器返回给POST请求的状态代码:

状态代码行为
200至299假定调用成功。
0-199、500+、超时(3秒)或网络错误临时故障。在出现以下时间的延迟后,将使用指数退避重试调用: * 30秒 * 1分钟(总共1.5分钟) * 2分钟(总共3.5分钟) * 4分钟(总共7.5分钟) * 8分钟(总共15.5分钟) * 16分钟(总共31.5分钟) * 32分钟(总共1小时3.5分钟) * 1小时4分钟(共2小时7.5分钟) * 2小时8分钟(共4小时15.5分钟) * 4小时16分钟(共8小时31.5分钟) * 8小时32分钟(共17小时3.5分钟) * 17小时4分钟(共34小时7.5分钟)

如果最后一次重试失败(状态码400+),调用将被记录为失败。

下一步

在验证Web视图中选择家长可以使用哪些验证方法(视地区而定)