Webhook

Webhook 是合作伙伴指定的网址，RBM 平台会将消息和事件发布到该网址。 此网址充当接收包含事件相关数据的 HTTPS POST 请求的端点。这意味着数据会通过 HTTPS 安全地发送到您的应用。

网络钩子网址可能如下所示：https://[your company name].com/api/rbm-events。 配置网络钩子后，您就可以开始接收消息和事件了。

合作伙伴网络钩子和代理网络钩子

您可以在合作伙伴级或代理级配置网络钩子。

  • 合作伙伴 Webhook 适用于您维护的每个代理。如果您的代理具有类似的行为，或者您只有一个代理，请使用合作伙伴 Webhook。
  • 代理网络钩子适用于各个代理。如果您运行多个行为各异的代理，可以为每个代理设置不同的 Webhook。

如果您同时配置了合作伙伴网络钩子和代理网络钩子，则代理网络钩子优先应用于其特定代理，而合作伙伴网络钩子适用于任何没有自己网络钩子的代理。

配置代理 webhook

您会在合作伙伴 webhook 中收到发送给代理的消息。如果您希望特定代理的消息到达其他 webhook，请设置代理 webhook。

  1. 打开 Business Communications 开发者控制台，然后使用您的 RBM 合作伙伴 Google 账号登录。
  2. 点击您的代理。
  3. 点击集成。
  4. 对于网络钩子，点击配置。
  5. 在网络钩子端点网址部分，输入 webhook 网址，以“https://”开头。
  6. 记下您的 clientToken 值。您需要使用它来验证您收到的消息是否来自 Google。

  7. 将 webhook 配置为接受具有指定 clientToken 参数的 POST 请求，并发送包含 secret 参数的纯文本值作为响应正文的 200 OK 响应。

    例如，如果您的 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);
});

  8. 在开发者控制台中，点击验证。RBM 验证您的 webhook 后，对话框将关闭。

验证收到的消息

由于 webhook 可以接收来自任何发件人的消息，因此您应先验证传入的消息是否由 Google 发送，然后再处理消息内容。

如需验证您收到的消息是否由 Google 发送，请按以下步骤操作：

  1. 提取消息的 X-Goog-Signature 标头。这是消息正文载荷的哈希 base64 编码副本。
  2. 对请求的 message.body 元素中的 RBM 载荷进行 Base-64 解码。
  3. 使用您的 Webhook 的客户端令牌（您在设置 Webhook 时指定）作为密钥，创建经过 base-64 解码的消息载荷的字节的 SHA512 HMAC，并对结果进行 base64 编码。
  4. 将 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);

消息处理

从网络钩子返回除 200 OK 以外的任何内容均视为传送失败。

开发者必须注意，以高频率发送消息会以高频率生成 Webhook 通知，因此必须设计代码以按预期频率处理通知。开发者务必要考虑可能会导致失败响应的情况，包括来自其 Web 容器的 500 响应、超时或上游失败。需要考虑的事项包括：

  • 验证您的 DDoS 防护是否已配置为可处理预期速率的 Webhook 通知。
  • 确认数据库连接池等资源不会耗尽，也不会产生超时或 500 响应。

开发者应设计其系统，以便异步处理 RBM 事件，并且不会阻止 webhook 返回 200 OK。

异步 webhook 处理

请务必不要在 webhook 本身内处理 RBM 事件。处理期间的任何错误或延迟都可能会影响 Webhook 返回代码：

同步 webhook 处理

递送失败时的行为

当 RBM 从网络钩子调用中收到 200 OK 以外的响应时，会使用退避和重试机制。RBM 会增加重试之间的等待时间，最长可达 600 秒。系统会继续重试 7 天，之后便会舍弃相应消息。

代理级 webhook 的影响

RBM 会在一个队列中为合作伙伴排队消息。如果合作伙伴使用代理级 webhook，请务必注意，一个 webhook 的失败会影响向其他 webhook 的传送。在失败消息的回退期间，系统会调用属于其他代理的网络挂接。 不过，随着失败的消息排队等待重试，整体传送率会下降，其他代理也会受到影响。

开发者必须了解此模型并相应地编写代码，尽可能接受消息并将其排队以供处理，从而最大限度地减少返回失败的机会。

后续步骤

配置网络钩子后，您的代理便可从测试设备接收消息。发送消息以验证设置。

下一页
Dialogflow