Webhook 通知 | 文件 - Roblox 創作者中心

與其手動監控遊戲中的所有事件和用戶請求，您可以設置 Webhook 以在第三方消息工具或可以接收 HTTP 請求的自定義端點上接收實時通知。這有助於您自動化通知管理工作流程，以減少手動處理通知的工作量。

目前，Roblox 完全支持 Discord 和 Slack 的 Webhook 通知。使用 Webhook 與其他第三方工具可能會面臨未接收到所有通知的風險。

Webhook 工作流程

Webhook 在兩個不同的應用程序或服務之間發送實時通知或數據，例如 Roblox 和第三方消息工具。與傳統 API 不同，傳統 API 需要您設置客戶端應用程序以向服務器發送請求以接收數據，Webhook 在事件發生時立即將數據發送到您的客戶端端點。它們對於自動化 Roblox 與您用於團隊協作的第三方應用程序之間的工作流程非常有用，因為它們允許實時數據共享和處理。

一旦您設置了 Webhook，當目標事件發生時，Roblox 會向您提供的 Webhook URL 發送請求。Webhook URL 然後將請求重定向到您的接收應用程序或自定義端點，該端點可以根據 Webhook 負載中包含的數據採取行動。這可能包括為 RTBF 合規性刪除數據、向用戶發送確認或觸發另一個事件。

支持的觸發器

Roblox 目前支持以下事件觸發器。

訂閱重新訂閱 - 當用戶重新訂閱時，會發送一條消息，包含訂閱和訂閱者的信息。
訂閱續訂 - 當用戶續訂時，會發送一條消息，包含訂閱和訂閱者的信息。
訂閱退款 - 當用戶收到訂閱的退款時，會發送一條消息，包含訂閱和訂閱者的信息。
訂閱購買 - 當用戶購買訂閱時，會發送一條消息，包含訂閱和訂閱者的信息。
訂閱取消 - 當用戶取消訂閱時，會發送一條消息，包含訂閱和訂閱者的信息，以及取消的原因。

有關訂閱事件及其字段的更多信息，請參見訂閱參考。

合規性

刪除權 / 刪除請求 - 當用戶根據適用的全球數據保護和隱私法規行使其永久刪除個人信息的權利時。更多信息可以在 RTBF 和創作者中找到。

商務

商務產品訂單退款 - 當用戶收到其商務產品訂單的退款或該訂單被取消時。
商務產品訂單已支付 - 當用戶已支付其商務產品訂單時。請注意，可能會出現重複的 Webhook 事件，因此您應使用唯一的商務訂單 ID 來去重事件。

在創作者儀表板上配置 Webhook

要通過 Webhook 接收通知，您需要配置一個訂閱特定事件以觸發通知的 Webhook。對於群組擁有的遊戲，只有群組擁有者可以配置和接收 Webhook 通知。

如果您正在設置 Webhook 並處理個人數據，請確保它們符合適用的數據保護和隱私法規。請參見 RTBF 和創作者獲取更多信息。

要設置 Webhook：

在創作者中心中選擇您的體驗。
在配置下，選擇 Webhook 並單擊添加 Webhook。

Webhook URL 來自您的提供者。例如，Slack 的 URL 可能看起來像這樣：
https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX
輸入您的 Webhook URL 和名稱。
可選
包含一個密鑰，這有助於確保您收到的通知來自 Roblox。更多信息，請參見驗證 Webhook 安全性。
從您想要接收通知的支持的觸發器事件列表中選擇一個或多個選項。
可選
使用測試響應按鈕檢查您的服務是否可以接收示例請求。
單擊保存更改。

目前，您最多可以配置 5 個 Webhook。

設置 Webhook URL

您可以設置一個自定義 HTTP 服務端點作為您的 Webhook URL，前提是它滿足以下要求：

必須可以公開訪問以處理請求。
可以處理 POST 請求。
可以在 5 秒內以 2XX 響應回應請求。
可以處理 HTTPS 請求。

當您的端點接收到 POST 請求時，它必須能夠：

從 POST 消息的主體中提取有關通知所需的詳細信息。
閱讀 POST 消息的主體，其中包含有關通知的通用詳細信息和與通知事件類型相關的具體詳細信息。

有關要處理的 POST 請求的架構的更多信息，請參見有效負載架構。

當 Webhook 通知因端點不可用等錯誤而無法到達您指定的 URL 時，Roblox 會使用固定的窗口大小重試向配置的 URL 發送消息 5 次。如果在 5 次嘗試後通知仍然無法送達，Roblox 將停止嘗試發送通知並假設該 URL 不再有效。在這種情況下，您需要使用可達到的 URL 更新您的 Webhook 配置，以便能夠接收通知。要排除故障並確認您的 Webhook URL 是否可以成功接收通知，請參見測試 Webhook。

第三方要求

第三方工具通常對 Webhook 有自己的要求，您需要在設置 Webhook URL 時遵循這些要求。您可以通過在目標工具的支持或文檔網站上搜索關鍵字 "webhook" 來找到這些要求。對於支持的第三方工具，請參見以下內容：

測試 Webhook

您可以測試您配置的 Webhook 是否可以在創作者儀表板上成功接收通知：

瀏覽到 Webhook 配置頁面。
從已配置的 Webhook 列表中選擇您想要測試的 Webhook。
單擊目標 Webhook 旁邊的鉛筆圖標。
單擊測試響應按鈕。

系統隨後會發送一個 SampleNotification 事件，其中包括觸發通知的用戶的用戶 ID，如下所示：

SampleNotification schema

{
  "NotificationId": "string",
  "EventType": "SampleNotification",
  "EventTime": "2023-12-30T16:24:24.2118874Z",
  "EventPayload": {
    "UserId": 1
  }
}

如果您將 Webhook 與第三方服務集成，您可以使用第三方 URL 測試它，以確認該服務可以成功接收來自您的 Webhook 的通知。如果您在配置 Webhook 時提供了一個密鑰，它還會生成一個 roblox-signature，您可以用來測試 roblox-signature 邏輯。

驗證 Webhook 安全性

在您配置服務器以接收有效負載後，它開始監聽發送到端點的任何有效負載。如果您在配置 Webhook 時設置了密鑰，Roblox 會在每個 Webhook 通知中發送一個 roblox-signature，以確保請求確實來自 Roblox。該簽名位於自定義端點的有效負載標頭中，並位於第三方服務器的頁腳中。

帶有自定義端點密鑰的簽名格式

t=<timestamp>,v1=<signature>

如果您沒有為 Webhook 設置密鑰，則簽名僅包含通知發送時的時間戳：

不帶密鑰的自定義端點簽名格式

t=<timestamp>

要驗證簽名：

提取時間戳和簽名值。所有帶有密鑰的 Webhook 的簽名共享相同的格式，作為 CSV 字符串，這兩個值後面跟著前綴：
- t: 通知發送的時間戳。
- v1: 使用創作者儀表板配置提供的密鑰生成的簽名值。
通過連接以下內容重新創建 roblox-signature 的基本字符串：
1. 將時間戳作為字符串。
2. 句點字符 .。
3. 請求主體的 JSON 字符串。
使用您在配置期間定義的密鑰作為密鑰，使用 SHA256 哈希函數計算基於哈希的消息身份驗證碼 (HMAC)，並使用您在第 2 步生成的基本字符串作為消息。將結果轉換為 Base64 格式以獲取預期的簽名。
將提取的簽名值與預期的簽名進行比較。如果您正確生成了簽名，則該值應該相同。
可選
為了防止重放攻擊，這是一種網絡攻擊，攻擊者攔截並重新發送數據以獲得未經授權的訪問或執行惡意操作，將提取的時間戳值與當前時間戳進行比較並確保其在合理的時間限制內是有幫助的。例如，10 分鐘的窗口通常是一個合理的時間限制。

有效負載架構

當您的 Webhook 的目標事件被觸發時，它會向您的 Webhook URL 發送請求，包括有關事件的信息在有效負載中。所有請求的有效負載共享相同的架構，由固定和可變字段組成。這確保了在有效負載中傳輸的數據是結構化和一致的，使接收應用程序更容易處理和使用數據。

固定有效負載架構字段可以幫助在所有 Webhook 請求中保持一致性，提供以下可用字段：

NotificationId (string): 每個發送的通知的唯一標識符。如果收到相同的 NotificationId 兩次，則視為重複。
EventType (string): 表示觸發通知的事件類型。
EventTime (string): 事件觸發的時間戳。

可變有效負載架構字段提供了 Webhook 的靈活性，以適應各種類型的事件，包括：

EventPayload (object): 包含特定於觸發 Webhook 的 EventType 的信息。EventPayload 架構的結構根據事件類型而有所不同。

以下示例顯示了刪除權請求事件的有效負載架構：

刪除權請求的示例架構

{
   "NotificationId": "string",
   "EventType": "RightToErasureRequest",
   "EventTime": "2023-12-30T16:24:24.2118874Z",
   "EventPayload": {
      "UserId": 1,
      "GameIds": [
         1234, 2345
      ]
   }
}

處理通知

如果您存儲任何用戶的個人可識別信息 (PII)，例如他們的用戶 ID，您應該根據您的法律義務評估請求。更多信息可以在 RTBF 和創作者中找到。您可以創建一個機器人來處理 Webhook 通知並幫助自動化數據刪除，前提是您在數據存儲中存儲 PII。請參見自動化刪除刪除權請求獲取有關如何在 Discord 中創建使用 Open Cloud API for data stores 刪除 PII 數據的機器人的示例。此示例可以調整以處理其他通知，例如訂閱事件。

如果您使用自定義端點作為 Webhook 服務器，而不是第三方工具，您可以從 Webhook 負載中提取要刪除的數據並構建自己的自動化解決方案。以下代碼示例是一個具有防止重放攻擊的服務器示例，通過驗證時間戳和請求是否來自 Roblox：

從有效負載中提取 PII

const crypto = require('crypto');
const express = require('express');

const secret = '<your_secret>' // 這可以設置為環境變量

let app = express();
app.use(express.json());

app.all('/*', function (req, res) {
   console.log('收到新請求');

   // 從標頭中提取時間戳和簽名
   const signatureHeader = req.headers['roblox-signature'].split(',');
   const timestamp = signatureHeader.find(e => e.startsWith('t=')).substring(2);
   const signature = signatureHeader.find(e => e.startsWith('v1=')).substring(3);

   // 確保請求在 300 秒的窗口內來防止重放攻擊
   const requestTimestampMs = timestamp * 1000;
   const windowTimeMs = 300 * 1000;
   const oldestTimestampAllowed = Date.now() - windowTimeMs;

   if (requestTimestampMs < oldestTimestampAllowed) {
      return res.status(403).send('請求已過期');
   }

   // 驗證簽名
   const message = `${timestamp}.${JSON.stringify(req.body)}`;
   const hmac = crypto.createHmac('sha256', secret);
   const calculatedSignature = hmac.update(message).digest('base64');

   if (signature !== calculatedSignature) {
      return res.status(401).send('未經授權的請求');
   }

   // 處理有效負載的邏輯
   const payloadBody = req.body;
   const eventType = payloadBody['EventType'];

   if (eventType === 'RightToErasureRequest'){
      const userId = payloadBody['EventPayload']['UserId'];
      const gameIds = payloadBody['EventPayload']['GameIds'];

      console.log(`有效負載數據: UserId=${userId} 和 GameIds=${gameIds}`);
      // 如果您在數據存儲中存儲 PII，請使用 UserId 和 GameIds 刪除數據存儲中的信息。
   }

   return res.json({ message: '成功處理消息' });
});

app.listen(8080, function () {
   console.log('服務器啟動');
});