Webhook

Webhook 是合作夥伴指定的網址，RCS for Business 平台會將訊息和事件發布至該網址。這個網址會做為端點，接收含有事件資料的 HTTPS POST 要求。這表示資料會透過 HTTPS 安全地傳送至應用程式。

Webhook 網址可能如下所示： https://[your company name].com/api/rbm-events。 設定 Webhook 後，即可開始接收訊息和事件。

合作夥伴 Webhook 和代理 Webhook

你可以在合作夥伴層級或代理層級設定 Webhook。

  • 合作夥伴 Webhook 會套用至您維護的每個代理程式。如果代理程式的行為類似，或只有一個代理程式，請使用合作夥伴 Webhook。
  • 服務專員 Webhook 適用於個別服務專員。如果您經營多個行為各異的代理程式，可以為每個代理程式設定不同的 Webhook。

如果您同時設定了合作夥伴 Webhook 和代理程式 Webhook，代理程式 Webhook 會優先套用至特定代理程式，而合作夥伴 Webhook 則會套用至沒有專屬 Webhook 的代理程式。

設定代理程式 Webhook

說明文件。

您會在合作夥伴 Webhook 收到傳送給代理程式的訊息。如要將特定服務專員的訊息傳送至其他 Webhook，請設定服務專員 Webhook。

  1. 開啟 Business Communications 開發人員控制台，然後使用 RCS for Business 合作夥伴 Google 帳戶登入。
  2. 按一下代理程式。
  3. 點選 [Integrations] (整合)。
  4. 按一下「Webhook」的「設定」。
  5. 在「Webhook 端點網址」部分，輸入開頭為「https://」的 Webhook 網址。
  6. 請記下 clientToken 值。您需要這項資訊，才能驗證收到的訊息是否來自 Google。

  7. 將 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);
});

  8. 在開發人員控制台中，按一下「驗證」。RCS for Business 驗證 Webhook 後，對話方塊就會關閉。

驗證收到的訊息

由於 Webhook 可以接收任何寄件者的訊息，因此您應先確認內送訊息是由 Google 傳送，再處理訊息內容。

如要確認您收到的訊息是否由 Google 傳送，請按照下列步驟操作：

  1. 擷取郵件的X-Goog-Signature標頭。這是郵件內文承載內容的雜湊副本，採用 Base64 編碼。
  2. 在要求的 message.body 元素中，以 Base64 解碼 RCS for Business 酬載。
  3. 使用網路鉤子的用戶端權杖 (設定網路鉤子時指定) 做為金鑰，建立 Base64 解碼訊息酬載位元組的 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 回應。

開發人員應設計系統，讓 RBM 事件的處理作業以非同步方式進行，且不會妨礙 Webhook 傳回 200 OK。

非同步處理 Webhook

請務必不要在 Webhook 本身處理 RBM 事件。處理期間發生任何錯誤或延遲，都可能影響 Webhook 回傳代碼：

同步處理 Webhook

傳送失敗時的行為

如果 Webhook 傳回的狀態不是 200 OK，RCS for Business 平台會使用退避和重試機制，重新傳送資料。也就是說，系統會逐步增加每次嘗試傳送之間的延遲時間，最終達到每個待處理訊息每 10 分鐘重試一次的頻率上限。系統會持續重試七天，之後就會永久刪除郵件。

服務專員層級 Webhook 的影響

RCS for Business 會將合作夥伴的訊息排入一個佇列。單一合作夥伴帳戶的所有服務專員共用一個佇列。因此，如果其中一個 Webhook 失敗，整個佇列就會遭到封鎖，導致所有代理商的使用者事件無法傳送給合作夥伴。

如果有多則未確認的訊息，重試事件可能會大幅增加。舉例來說，如果服務專員未確認 1,600 份送達收據，且重試頻率達到 10 分鐘的限制，則每天可能會產生約 230,000 個潛在錯誤：

每天 1,600 封郵件 × 每小時 6 次重試 × 每天 24 小時 = 每天約 230,000 個錯誤

大量重試可能會導致共用的 Pub/Sub 佇列遭到封鎖，並大幅延遲合作夥伴所有廣告活動的使用者事件接收作業。

最佳做法

如要確保實際工作環境流量的可靠性，並避免佇列阻斷，請採用下列最佳做法：

  • 立即傳回 200 OK：Webhook 應會收到訊息、將訊息儲存在本機佇列，並在五秒內傳回 200 OK 回應。
  • 處理程序分離：使用個別的背景工作站，處理本機佇列中的訊息邏輯。
  • 監控測試代理：將開發代理視為正式代理，因為如果開發代理失敗，也會封鎖共用的合作夥伴佇列。
  • 專門用於測試的帳戶：建議使用一個開發人員帳戶來管理正式版代理程式，並使用另一個開發人員帳戶來管理測試版代理程式。
  • 驗證 Google 流量：使用反向 DNS 或 X-Goog-Signature 標頭，而非固定 IP 允許清單，因為 Google 使用動態任播 IP。如要進一步瞭解如何手動驗證及找出 Google IP 範圍，請參閱「驗證 Google 要求」文件，特別是使用者觸發的擷取器和 Google 使用者觸發的擷取器的 JSON 檔案。

後續步驟

設定 Webhook 後，代理程式就能接收測試裝置傳送的訊息。傳送訊息來驗證設定。

下一頁
Dialogflow