Configure the PV service webhook

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

阅读时间4分钟

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

如果你要配置网钩（webhook），你需要：

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

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

在 家长验证（Parent Verification） 选项卡中，输入 验证成功的网钩URL（Successful verification webhook URL） 。这是KWS发送网钩确认验证成功的位置。
重要提示：
- 不要在网钩URL中包含容易被攻击者操纵的信息（例如，可以轻松迭代的数字ID）。
- 不要在你的URL中包含特殊字符。
点击 发布到测试（Publish to Test） 。

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

点击查看大图。

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

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

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

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

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

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

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

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

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

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

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

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

例如：

注意：当请求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+	最后一次重试失败。调用将被记录为失败。