网络钩子是合作伙伴创建的 HTTPS 回调,用于指定代理应如何响应消息和事件。配置网络钩子后,您就可以开始接收消息和事件了。
合作伙伴网络钩子和代理网络钩子
您可以在合作伙伴级别或代理级别配置网络钩子。
- 您的合作伙伴网络钩子适用于您维护的每个代理。如果您的代理具有类似行为,或者您只有一个代理,请使用合作伙伴网络钩子。
- 代理 Webhook 适用于各个客服人员。如果您运营多个代理且行为不同,则可以为每个代理设置不同的 webhook。
如果您同时配置了合作伙伴网络钩子和代理网络钩子,则代理网络钩子将在其特定代理上优先,而合作伙伴网络钩子适用于没有自己的网络钩子的所有代理。
配置代理 webhook
您会在合作伙伴网络钩子处收到发送给客服人员的消息。如果您希望特定代理的消息到达其他 webhook,请设置代理 webhook。
- 打开 Business Communications 开发者控制台,然后使用您的 RBM 合作伙伴 Google 帐号登录。
- 点击您的代理。
- 点击集成。
- 对于网络钩子,点击配置。
- 在网络钩子端点网址部分,输入以“https://”开头的网络钩子网址。
- 记下您的
clientToken
值。您需要使用它来验证您收到的消息是否来自 Google。 将您的 webhook 配置为接受具有指定
clientToken
参数的POST
请求,并发送200 OK
响应(其中包含secret
参数的纯文本值作为响应正文)。例如,如果您的 webhook 收到具有以下正文内容的
POST
请求{ "clientToken":"SJENCPGJESMGUFPY", "secret":"1234567890" }
那么您的 Webhook 应确认
clientToken
值,如果clientToken
正确,则返回200 OK
响应,并将1234567890
作为响应正文:// clientToken from Configure const myClientToken = "SJENCPGJESMGUFPY"; // Example endpoint app.post("/rbm-webhook", (req, res) => { const msg = req.body; if (msg.clientToken === myClientToken) { res.status(200).send(msg.secret); return; } res.send(400); });
在 Developer Console 中,点击验证。RBM 验证您的 webhook 后,该对话框会关闭。
验证收到的邮件
由于网络钩子可以接收来自任何发送者的消息,因此您应在处理消息内容之前验证 Google 是否发送了传入消息。
要验证 Google 是否向您发送了邮件,请按以下步骤操作:
- 提取邮件的
X-Goog-Signature
标头。这是消息正文载荷的经过哈希处理的 base64 编码副本。 - 对请求的
message.body
元素中的 RBM 载荷进行 Base-64 解码。 - 使用网络钩子的客户端令牌(您在设置网络钩子时指定)作为密钥,创建由 base-64 解码消息载荷的字节组成的 SHA512 HMAC,并对结果进行 base64 编码。
- 将
X-Goog-Signature
哈希与您创建的哈希进行比较。- 如果哈希值一致,则表示您已确认该邮件是 Google 发送的。
如果哈希值不匹配,请检查已知良好的消息的哈希处理过程。
如果您的哈希处理过程正常运行,并且收到了您认为以欺诈方式发送给您的消息,请与我们联系。
Node.js
if ((requestBody.hasOwnProperty('message')) && (requestBody.message.hasOwnProperty('data'))) { // Validate the received hash to ensure the message came from Google RBM let userEventString = Buffer.from(requestBody.message.data, 'base64'); let hmac = crypto.createHmac('sha512', CLIENT_TOKEN); let data = hmac.update(userEventString); let genHash = data.digest('base64'); let headerHash = req.header('X-Goog-Signature'); if (headerHash === genHash) { let userEvent = JSON.parse(userEventString); console.log('userEventString: ' + userEventString); handleMessage(userEvent); } else { console.log('hash mismatch - ignoring message'); } } res.sendStatus(200);
消息处理
如果从 webhook 返回除 200 OK
以外的任何内容,则视为传送失败。
开发者必须注意,以高速率发送消息将产生高速率 webhook 通知,并且必须设计其代码以确保能够以预期速率使用通知。开发者必须考虑可能导致故障响应的情况,包括来自其网络容器的 500
响应、超时或上游故障。要考虑的事项包括:
- 确保您的 DDoS 防护功能配置为可处理 webhook 通知的预期速率。
- 确保数据库连接池等资源不会用尽,并产生超时或
500
响应。
递送失败时的行为
当从 webhook 调用收到 200 OK
以外的响应时,RBM 会使用退避和重试机制。RBM 会增加重试之间的等待时间,最多可增加 600 秒。停用将持续 7 天,之后该消息将被舍弃。
代理级 webhook 的影响
RBM 将合作伙伴的消息加入一个队列。如果合作伙伴使用的是代理级 webhook,请务必注意,一个 webhook 发生故障将影响到其他 webhook 的传送。在失败消息的退避期内,系统会调用属于其他代理的 webhook,但随着失败消息排队等待重试,总体传送速率会下降,其他代理也会受到影响。
开发者务必要相应地理解此模型和代码 - 尽可能多地接受消息并将其排入队列以进行处理,以最大限度地减少返回失败的可能性。