Webhook 通知

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

Webhook 工作流程

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

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

支援的觸發器

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

訂閱

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

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

合規性

• 刪除請求的權利 - 當用戶根據 通用數據保護條例（GDPR）提交數據刪除請求時。

商務

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

在創作者儀表板上配置 Webhook

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

要設置 Webhook：

1. 在 創作者中心 中選擇您的經驗。

2. 在 配置 下，選擇 Webhook 並單擊 添加 Webhook。

   Webhook URL 來自您的提供者。例如，一個 Slack URL 可能如下所示：

   https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX

3. 輸入您的 Webhook URL 和名稱。

4. （可選）包含一個密鑰，該密鑰有助於確保您收到的通知來自 Roblox。如需更多信息，請參見 驗證 Webhook 安全性。

5. 從您想要接收通知的 支援的觸發器 事件列表中選擇一個或多個選項。

6. （可選）使用 測試響應 按鈕檢查您的服務是否能接收示例請求。

7. 單擊 保存更改。

設置 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”來找到這些要求。對於支援的第三方工具，請參見以下內容：

• Discord 幫助中心
• Slack API 參考

測試 Webhook

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

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

系統將發送一個 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>

要驗證簽名：

1. 提取時間戳和簽名值。所有具有密鑰的 Webhook 的簽名都共享與這兩個值格式相同的 CSV 字符串，其中有這些前綴：

   • t：通知發送時的時間戳。
   • v1：使用創作者儀表板配置提供的密鑰生成的簽名值。

2. 通過連接以下內容來重新創建 roblox-signature 的基本字符串：

   1. 將時間戳作為字符串。
   2. 句點字符 .。
   3. 請求正文的 JSON 字符串。

3. 使用在配置期間定義的密鑰作為密鑰，並使用通過步驟 2 生成的基字符串計算 HMAC 的 SHA256 哈希函數。將結果轉換為 Base64 格式以獲取預期的簽名。

4. 將提取到的簽名值與預期的簽名進行比較。如果您正確生成了簽名，該值應該相同。

5. （可選）為了防止重放攻擊，這是一種網絡攻擊類型，攻擊者攔截並重新發送數據以獲得未經授權的訪問或執行惡意操作，將提取的時間戳值與當前時間戳進行比較，並確保其在合理的時間限度內。例如，10 分鐘的窗口通常是合理的時間限度。

有效載荷架構

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

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

1. NotificationId（字符串）：每個發送通知的唯一標識符。如果收到相同的 NotificationId 兩次，則它被視為重複。
2. EventType（字符串）：指示觸發通知的事件類型。
3. EventTime（字符串）：事件被觸發的時間戳。

可變有效載荷架構字段提供了靈活性，使 Webhook 能夠適應各種事件類型，其中包括：

1. EventPayload（對象）：包含與觸發 Webhook 的 EventType 相關的信息。EventPayload 的架構根據事件類型的不同而有所不同。

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

刪除權請求的示例架構
{
   "NotificationId": "string",
   "EventType": "RightToErasureRequest",
   "EventTime": "2023-12-30T16:24:24.2118874Z",
   "EventPayload": {
      "UserId": 1,
      "GameIds": [
         1234, 2345
      ]
   }
}

處理通知

如果您存儲任何用戶的 個人可識別信息 (PII)，例如他們的用戶 ID，當用戶提交此類請求時，您必須刪除此信息以遵守 GDPR 刪除權 合規要求。您可以創建一個機器人來處理 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('伺服器啟動');
});