/*@jsxRuntime automatic @jsxImportSource react*/ const {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0]; const {useMDXComponents: _provideComponents} = arguments[0]; function _createMdxContent(props) { const _components = Object.assign({ h2: "h2", p: "p", code: "code", ul: "ul", li: "li", a: "a", strong: "strong", ol: "ol", h3: "h3", pre: "pre", table: "table", thead: "thead", tr: "tr", th: "th", tbody: "tbody", td: "td" }, _provideComponents(), props.components), {Note, Lightbox} = _components; if (!Lightbox) _missingMdxReference("Lightbox", true); if (!Note) _missingMdxReference("Note", true); return _jsxs(_Fragment, { children: [_jsx(_components.h2, { id: "介绍", children: "介绍" }), "\n", _jsxs(_components.p, { children: ["当家长使用家长验证服务成功验证其身份时，KWS通过网钩调用发送 ", _jsx(_components.code, { children: "parent-verified" }), " 事件来通知你的系统。"] }), "\n", _jsx(_components.p, { children: "如果你要配置网钩（webhook），你需要：" }), "\n", _jsxs(_components.ul, { children: ["\n", _jsxs(_components.li, { children: [_jsx(_components.a, { href: "#%E8%AE%BE%E7%BD%AE%E4%BD%A0%E7%9A%84%E7%BD%91%E9%92%A9url", children: "提供KWS向其发送网钩的URL" }), "。"] }), "\n", _jsxs(_components.li, { children: ["使用KWS在 ", _jsx(_components.strong, { children: "家长验证（Parent Verification）" }), " 选项卡产品集成细节中提供的 ", _jsx(_components.strong, { children: "网钩密钥代码（Webhook secret code）" }), " ", _jsx(_components.a, { href: "#%E4%BD%BF%E7%94%A8%E5%AF%86%E9%92%A5%E4%BB%A3%E7%A0%81%E7%94%9F%E6%88%90%E4%BD%A0%E7%9A%84%E7%AD%BE%E5%90%8D", children: "生成签名" }), "。密钥代码用于签署负载，确认网钩是来自KWS的真实调用。"] }), "\n"] }), "\n", _jsx(Note, { children: _jsx(_components.p, { children: "注意：你的测试环境和生产环境都带有自己独特的网钩密钥代码。" }) }), "\n", _jsx(_components.h2, { id: "设置你的网钩url", children: "设置你的网钩URL" }), "\n", _jsxs(_components.ol, { children: ["\n", _jsxs(_components.li, { children: ["\n", _jsxs(_components.p, { children: ["要访问你的家长验证服务设置，请在 ", _jsx(_components.strong, { children: "操作面板" }), " 中选择产品，然后点击 ", _jsx(_components.strong, { children: "服务（Services）" }), " 选项卡，在 ", _jsx(_components.strong, { children: "家长验证（Parent Verification）" }), " 面板中点击 ", _jsx(_components.strong, { children: "查看或编辑（View or Edit）" }), "。"] }), "\n"] }), "\n", _jsxs(_components.li, { children: ["\n", _jsxs(_components.p, { children: ["在 ", _jsx(_components.strong, { children: "家长验证（Parent Verification）" }), " 选项卡中，输入 ", _jsx(_components.strong, { children: "验证成功的网钩URL（Successful verification webhook URL）" }), " 。这是KWS发送网钩确认验证成功的位置。"] }), "\n", _jsxs(Note, { children: [_jsx(_components.p, { children: "重要提示：" }), _jsxs(_components.ul, { children: ["\n", _jsx(_components.li, { children: "不要在网钩URL中包含容易被攻击者操纵的信息（例如，可以轻松迭代的数字ID）。" }), "\n", _jsx(_components.li, { children: "不要在你的URL中包含特殊字符。" }), "\n"] })] }), "\n"] }), "\n", _jsxs(_components.li, { children: ["\n", _jsxs(_components.p, { children: ["点击 ", _jsx(_components.strong, { children: "发布到测试（Publish to Test）" }), " 。"] }), "\n"] }), "\n"] }), "\n", _jsx(_components.h2, { id: "使用密钥代码生成你的签名", children: "使用密钥代码生成你的签名" }), "\n", _jsxs(_components.p, { children: ["点击 ", _jsx(_components.strong, { children: "发布到测试（Publish to Test）" }), " 后，会显示 ", _jsx(_components.strong, { children: "网钩密钥代码（Webhook secret code）" }), " ："] }), "\n", _jsx(Lightbox, { src: "/assets/kids-web-services/set-up-pv-service/config-pv-webhook/secret-code.png", alt: "密钥代码", width: 650, children: _jsx(_components.p, { children: "点击查看大图。" }) }), "\n", _jsx(_components.h3, { id: "示例", children: "示例" }), "\n", _jsx(_components.p, { children: "此示例展示了如何使用密钥代码创建签名。" }), "\n", _jsx(_components.p, { children: "KWS会向你发送网钩。网钩调用是HTTPS POST，它具有封装事件特定负载的通用结构：" }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { className: "language-bash", children: "POST https://www.yourdomain.com/your-webhook-endpoint\nx-kws-signature: t=1621535329,v1=f7bc83f430538424b13298e6aa6fb143ef4d59a14946175997479dbc2d1a3cd8\nBody\n{\n \"name\": \"webhook-name\",\n \"time\": \"ISO8601 timestamp\",\n \"orgId\": \"uuid\",\n \"productId\": \"uuid\" | null,\n \"environmentId\": \"uuid\" | null,\n \"payload\": { ... type-specific payload ... }\n}\n" }) }), "\n", _jsx(_components.p, { children: "POST调用的头文件具有以下结构：" }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { className: "language-bash", children: "x-kws-signature: t=,v1=[,v1=]\n" }) }), "\n", _jsxs(_components.p, { children: ["其中通过HMAC_SHA256使用头文件中的时间戳值、在 ", _jsx(_components.strong, { children: "家长验证（Parent Verification）" }), " 选项卡的产品集成细节中显示的 ", _jsx(_components.strong, { children: "网钩密钥代码（Webhook secret code）" }), " 以及POST正文生成。"] }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { className: "language-js", children: "const timestamp = /* extracted value of 't=' from the header */;\nconst body = /* raw request body as UTF-8 string */;\nconst secretKey = /* secret key, as provided in the Developer Portal */;\nconst signature = crypto\n .createHmac('sha256', secretKey)\n .update('${timestamp}.${body}')\n .digest('hex');\n" }) }), "\n", _jsxs(_components.p, { children: ["在你的产品方面，你需要使用上述代码和时间戳、", _jsx(_components.strong, { children: "网钩密钥代码" }), " 和POST正文创建相同的签名。如果你创建的签名与我们在网钩调用的头文件中传递给你的v1签名匹配，那么你可以确认网钩是由我们发送的。"] }), "\n", _jsx(_components.p, { children: "通过你的Web服务器/Web应用程序显示公共端点（类似于你构建其他API端点的方式）。此端点采用下述POST正文，并验证签名头文件。" }), "\n", _jsx(Note, { children: _jsx(_components.p, { children: "注意：使用原始POST正文很重要。不要尝试解析和重新字符串化JSON，因为这可能会由于JSON库实现中的不一致而导致签名不匹配。" }) }), "\n", _jsx(_components.h3, { id: "post正文结构", children: "POST正文结构" }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { className: "language-bash", children: "POST https://www.yourdomain.com/your-webhook-endpoint\nx-kws-signature: t=,v1=[,v1=]\nBody\n{\n \"name\": \"webhook-name\",\n \"time\": \"ISO8601 timestamp\",\n \"orgId\": \"uuid\",\n \"productId\": \"uuid\" | null,\n \"environmentId\": \"uuid\" | null,\n \"payload\": { ... type-specific payload ... }\n}\n" }) }), "\n", _jsx(_components.h3, { id: "签名", children: "签名" }), "\n", _jsx(_components.p, { children: "要确认网钩确实来自KWS，请将你生成的v1签名与你从KWS收到的网钩调用的头文件中的v1签名进行比较。如果签名匹配，你可以确认调用来自KWS。" }), "\n", _jsxs(_components.p, { children: ["签名是十六进制格式（小写）的HMAC_SHA256哈希，其中密钥是我们在 ", _jsx(_components.strong, { children: "家长验证（Parent Verification）" }), " 选项卡中为你提供的 ", _jsx(_components.strong, { children: "网钩密钥代码（Webhook secret code）" }), " 。"] }), "\n", _jsx(_components.p, { children: "签名通过以下格式的x-kws-signature头文件发送：" }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { className: "language-bash", children: "x-kws-signature: t=,v1=[,v1=]\n" }) }), "\n", _jsxs(Note, { children: [_jsx(_components.p, { children: "注意：目前仅包含一个v1签名，但在以下情况下，头文件可能包含多个签名：" }), _jsxs(_components.ul, { children: ["\n", _jsx(_components.li, { children: "支持签名密钥轮换（将在过渡期内为先前和当前密钥发送签名）。" }), "\n", _jsx(_components.li, { children: "签名算法发生变化（v2签名将在过渡期内与v1签名一起发送）。" }), "\n"] })] }), "\n", _jsx(_components.p, { children: "生成v1签名的算法是包含在签名头文件中的时间戳的HMAC_SHA256，后跟句点（'.'），然后是原始请求正文。使用网钩的密钥代码初始化HMAC。" }), "\n", _jsx(_components.p, { children: "例如：" }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { className: "language-js", children: "const timestamp = /* extracted value of ‘t=' from the header */;\nconst body = /* raw request body as UTF-8 string */;\nconst secretKey = /* the webhook secret code from the %Parent Verification% tab. */;\nconst signature = crypto\n .createHmac('sha256', secretKey)\n .update(`${timestamp}.${body}`)\n .digest('hex');\n" }) }), "\n", _jsx(Note, { children: _jsx(_components.p, { children: "注意：当请求URL可能被修改时，系统会故意不将网钩URL包含在签名算法中，以便在反向代理/负载平衡器等背后的服务中更轻松地进行签名验证。" }) }), "\n", _jsx(_components.h2, { id: "网钩重试行为", children: "网钩重试行为" }), "\n", _jsx(_components.p, { children: "网钩重试行为取决于你的服务器返回给POST请求的状态代码：" }), "\n", _jsxs(_components.table, { children: [_jsx(_components.thead, { children: _jsxs(_components.tr, { children: [_jsx(_components.th, { children: _jsx(_components.strong, { children: "状态代码" }) }), _jsx(_components.th, { children: _jsx(_components.strong, { children: "行为" }) })] }) }), _jsxs(_components.tbody, { children: [_jsxs(_components.tr, { children: [_jsx(_components.td, { children: "200至299" }), _jsx(_components.td, { children: "假定调用成功。" })] }), _jsxs(_components.tr, { children: [_jsx(_components.td, { children: "0-199、400+、500+、超时（3秒）或网络错误" }), _jsxs(_components.td, { children: ["临时故障。在出现以下时间的延迟后，将使用指数退避重试调用：", _jsxs("ul", { children: [_jsx("li", { children: "30秒" }), _jsx("li", { children: "1分钟（总共1.5分钟）" }), _jsx("li", { children: "2分钟（总共3.5分钟）" }), _jsx("li", { children: "4分钟（总共7.5分钟）" }), _jsx("li", { children: "8分钟（总共15.5分钟）" }), _jsx("li", { children: "16分钟（总共31.5分钟）" }), _jsx("li", { children: "32分钟（总共1小时3.5分钟）" }), _jsx("li", { children: "1小时4分钟（共2小时7.5分钟）" }), _jsx("li", { children: "2小时8分钟（共4小时15.5分钟）" }), _jsx("li", { children: "4小时16分钟（共8小时31.5分钟）" }), _jsx("li", { children: "8小时32分钟（共17小时3.5分钟）" }), _jsx("li", { children: "17小时4分钟（共34小时7.5分钟）" })] })] })] })] })] }), "\n", _jsx(_components.h2, { id: "下一步", children: "下一步" }), "\n", _jsxs(_components.p, { children: [_jsx(_components.a, { href: "/kids-web-services/set-up-pv-service/config-api", children: "接入KWS API在验证网络视图中选择家长可用的验证方法（视地区而定）" }), "。"] })] }); } function MDXContent(props = {}) { const {wrapper: MDXLayout} = Object.assign({}, _provideComponents(), props.components); return MDXLayout ? _jsx(MDXLayout, Object.assign({}, props, { children: _jsx(_createMdxContent, props) })) : _createMdxContent(props); } return { default: MDXContent }; function _missingMdxReference(id, component) { throw new Error("Expected " + (component ? "component" : "object") + " `" + id + "` to be defined: you likely forgot to import, pass, or provide it."); }