Webhook

网络钩子是合作伙伴创建的 HTTPS 回调,用于指定代理应如何响应消息和事件。配置 Webhook 后,您就可以开始接收消息事件了。

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

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

  • 您的合作伙伴 webhook 会应用于您维护的每个客服人员。如果您的客服人员具有类似的行为,或者您只有一位客服人员,请使用合作伙伴 Webhook
  • 代理 Webhook 适用于各个客服人员。如果您运营多个具有不同行为的客服人员,可以为每个客服人员设置不同的 webhook

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

配置代理 webhook

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

  1. 打开 Business Communications 开发者控制台,然后使用您的 RBM 合作伙伴 Google 账号登录。
  2. 点击您的代理。
  3. 点击集成
  4. 对于网络钩子,点击配置
  5. 网络钩子端点网址部分,输入以“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. 在 Play 管理中心内,点击验证。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);
  

消息处理

如果通过 webhook 返回的不是 200 OK,则会被视为传送失败。

开发者必须注意,以较高的速率发送消息会以较高的速率生成 webhook 通知,因此必须设计代码,确保其能够以预期的速率使用通知。开发者务必要考虑可能导致失败响应的情况,包括来自其网站容器的 500 响应、超时或上游失败。需要考虑的事项包括:

  • 确保您的 DDoS 防护配置为处理预期的 webhook 通知速率。
  • 确保数据库连接池等资源不会耗尽,并产生超时或 500 响应。

递送失败时的行为

当从 webhook 调用收到 200 OK 以外的响应时,RBM 会使用退避和重试机制。RBM 会增加重试之间的等待时间,最长可达 600 秒。退役消息将持续显示 7 天,之后便会下架。

代理级 webhook 的影响

RBM 会将合作伙伴的消息加入一个队列。如果合作伙伴使用的是代理级 webhook,请务必注意,一个 webhook 发生故障将影响到其他 webhook 的传送。在失败消息的回退期内,系统会调用其他代理的 Webhook,但随着失败消息加入队列以进行重试,整体传送率会下降,其他代理也会受到影响。

开发者必须了解这种模式并相应地编写代码,尽可能接受消息并将其加入队列以进行处理,以最大限度地减少返回失败的可能性。

后续步骤

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