ウェブホーク通知

*このコンテンツは、ベータ版のAI（人工知能）を使用して翻訳されており、エラーが含まれている可能性があります。このページを英語で表示するには、 こちら をクリックしてください。

エクスペリエンス内のすべてのイベントとユーザーからのリクエストを手動でモニタリングする代わりに、ウェブコールを設定して、サードパーティのメッセージツールまたはカスタムエンドポイントで実時間通知を受信できます。これにより、手動のエラー処理の通知を減少できます。通知管理ワークフローを自動化して、手動のエラー処理の通知を減少する

ウェブホークのワークフロー

ウェブコールは、Roblox などのサードパーティのメッセージツールを介して、2つの異なるアプリまたはサービス間で実時間の通知やデータを送信するために、実時間の通知を送信します。通常の API では、クライアントアプリを設定して、サーバーにデータ

ウェブホークを設定すると、ターゲットイベントが発生するたびに、Roblox は、提供するウェブホーク URL にリクエストを送信します。ウェブホーク URL は、ウェブホークの貨物に含まれるデータに基づいて、受信アプリケーションまたはカスタムエンドポイントにリクエストをリンダーします。これには、データを

サポートされたトリガー

Roblox は現在、通知のための次のイベントトリガーをサポートしています：

  • サブスクリプションがキャンセルされました。 - ユーザーがサブスクリプションをキャンセルすると、サブスクリプションとサブスクリプションの所有者、そしてキャンセルの理由が含まれたメッセージが送信されます。
  • サブスクリプション購入済み - ユーザーがサブスクリプションを購入すると、サブスクリプションとサブスクリプションの所有者が含まれたメッセージが送信されます。
  • サブスクリプションの返金完了 - ユーザーがサブスクリプションの返金を受け取ったとき、サブスクリプションとサブスクリプションの所有者が含まれたメッセージが送信されます。
  • サブスクリプション更新済み - ユーザーがサブスクリプションを更新すると、サブスクリプションとサブスクリプションの所有者に関するメッセージが送信されます。
  • サブスクリプション再購読 - ユーザーがサブスクリプションに再購読すると、サブスクリプションとサブスクリプションの所有者に関するメッセージが送信されます。
  • 「忘れられる権利」 データ削除リクエストは、一般データ保護規範 ( GDPR ) の下で。

サブスクリプションイベントとそのフィールドに関する詳細は、クラウド API サブスクリプション 参照してください。

クリエイターダッシュボードの Webhook の構成

ウェブコールを通じて通知を受信するには、特定のイベントにサブスクリプトするウェブコールを構成する必要があります。グループが所有するエクスペリエンスの場合、グループ所有者のみがウェブコール通知を構成し、受信できます。

ウェブホークを設定するには：

  1. ナビゲート to the Webhook ホールド セクション of the クリエイターダッシュボード。
  2. クリックしてください ウェブホークを追加 ボタン。
  3. 設定フィールドを完了してください：
    1. Webhook URL — 通知を受信し、サードパーティのウェブホーク URL を受信するための URL を指定します。For more information on the requirements, see Webhook URL の設定 .
    2. 名前 — コンフィグを他のコンフィグと区別するために、カスタム名を使用してください。デフォルトでは、値は Webhook URL と同じです。
    3. 秘密 (オプション) — 受信した通知が RoblRoblox（ロブロックス） から来ているかを確認したい場合は、秘密を提供します。詳細は、「Webhook のセキュリティを検証」を参照してください。
    4. トリガー — イベントの通知を受信するトリガーのリストの サポートされたトリガー の 1つまたは複数を選択します。
  4. クリックします[変更を保存]**ボタン。

Webhook URL の設定

次の要件を満たしている場合、カスタムHTTPサービスエンドポイントをウェブホック URL として設定できます：

  • リクエストを処理するために公開されている必要があります。
  • ポストリクエストを処理できます。
  • 5秒以内に 2XX の応答を返すことができます。
  • HTTPS リクエストを処理できます。

エンドポイントが POST リクエストを受信すると、次のことができる必要があります：

  • ポストメッセージのボディから通知に必要な詳細を抽出します。
  • 通知とイベントタイプに関連するポストメッセージのボディを読んでください。

扱いたい POST リクエストのスキーマについては、Payload Schema を参照してください。

配信失敗の再試行ポリシー

エラーが端末の利用不可能などの理由で、ウェブホーク通知が指定された URL に到達できませんので、Roblox はメッセージを固定のウィンドウサイズで 5 回送信します。メッセージが 5 回も送信されない場合、

第三者の要件

サードパーティツールは通常、ウェブホーク URL を設定するときにフォローする必要があるウェブホークの要件を持っています。これらの要件は、ターゲットツールのサポートまたはドキュメントサイトで「webhook」キーワードを検索することで見つけることができます。サポートされている 3つのサードパーティツールの場合、フォロー中の 3つのツールを見てください：

ウェブコールをテスト中

配信したウェブホックをクリエイターダッシュボードで受信できるかどうかをテストすることができます。

  1. ナビゲート to the Webhook 配信ページ ページ。

  2. 設定されたウェブクールのリストからテストするウェブホークを選択します。

  3. ターゲットウェブフックの隣にあるペンのアイコンをクリックします。

    The pencil icon next to an example webhook

  4. クリックする テストレポート ボタン。

次に、SampleNotification タイプの通知を送信します。これには、ユーザーが通知をトリガーするユーザーの ユーザーID が含まれます。次の例のスキーマに示すように、ユーザーが通知をトリガーするときにユーザーの 身元証明書 が含まれます。

SampleNotification スキーマ
Body: {

  "NotificationId": "string",

  "EventType": "SampleNotification",

  "EventTime": "2023-12-30T16:24:24.2118874Z", // タイプ: ISO 8601 タイムスタンプ

  "EventPayload": {

    "UserId": 1 // タイプ: 長

  }

}

ウェブホークをサードパーティのサービスに統合する場合、サービスがウェブホークから通知を受信できるかを確認するために、サードパーティの URLを使用してテストを実行できます。ウェブホークを構成するときに秘密を提供すると、サービスに roblox-signature ロジックをテストするた

ウェブホークのセキュリティを検証する

サーバーにプロジェクトを受信するように設定すると、端末に送信されたすべてのプロジェクトをスキャンし始めます。Roblox がウェブホークの設定を構成すると、サーバーに roblox-signature が含まれたプロジェクトが送信

Signature Format with Secret for Custom Endpoints
"roblox-signature": "t=<timestamp>,v1=<signature>"

ウェブホークの秘密がない場合、受信したサインには、通知が送信されたときのタイムスタンプのみが含まれています：

Signature Format without Secret for Custom Endpoints
"roblox-signature": "t=<timestamp>"

署名を検証するには：

  1. 時刻と署名の値を抽出します。秘密の Webhook のすべてのサインチャーには、これらの 2つの値に続く CSV 文字列の形式と同じフォーマットが共有されます。

    • t : 通知が送信されるときのタイムスタンプト値。
    • v1 : クリエイターダッシュボードの構成によって生成されたサインチャー値。これらの 2つの値を split() 機能を使用して抽出できます。この場合、 , 文字で構成されたストリングベースのサインチャーは、0> v10> です。

  2. 再作成するベースストリングのベースは、次のコードで構成されています：

    1. 時刻を文字列字として保存します。
    2. 期間キャラクター . 。
    3. リクエストボディの JSON 文。

  3. コンフィグのキーとベースストリングを生成するステップ 2 を使用して、SHA256 ハッシュ関数を使用してハッシュベースメッセージの認証コードを計算します (HMAC)。結果を Base64 形式に変換して期待されるサインを取得します。

  4. 抽出されたシグネチャー値をエクスペリエンスしてください。シグネチャーを正しく生成した場合、値は同じであるべきです。

  5. (オプション) 再プレイ攻撃を防止するために、攻撃者がデータをインターセプトして再送信して不正なアクセスを獲得するために、または悪意のあるアクションを実行するために、取得されたタイムスタンプ値と現在のタイムスタンプを比較して、理想的な時間制限内に落ちることができます。たとえば、10分間のウィ

Payload スキーマ

ウェブホックのターゲットイベントがトリガーされると、ウェブホック URL にリクエストが送信され、イベントの詳細がペイロードに含まれています。すべてのペイロードのリクエストは、固定と変数のフィールドで構成されたスキーマを共有します。これにより、受信アプリケーションがデータを処理および使用するのが簡単に

固定されたエラーのスキーマフィールド は、すべてのウェブホークリクエストで一貫性を維持するために役立つことができます。これには、次のフィールドが含まれます：

  1. NotificationId 、string : 各通知に対するユニークな識別子。如果同じ NotificationId が 2 回受信されると、重複として扱われます。
  2. EventType , string : 文字列は、通知がトリガーされたイベントの種類を表示します。
  3. EventTime , timestamp : イベントがトリガーされたときのおよその時刻を指す。

変数のロードアウトスキーマフィールド は、ウェブホークを含むさまざまな種類のイベントに対応できるように柔軟性を提供します：

  1. EventPayload、object：ウェブホークをトリガーする EventType に関する情報を含みます。0> EventPayload0> スキーマの構造は、イベントの種類によって変わります。

次の例では、 Right To Erasure Request イベントの荷物スキーマを示しています：

右の消去リクエストのスキーマの例
Body:{



   "NotificationId": "string",



   "EventType": "RightToErasureRequest",



   "EventTime": "2023-12-30T16:24:24.2118874Z",



   "EventPayload": {



      "UserId": 1, // タイプ: 長



      "GameIds": [ // タイプ: 長の列列の配列



         1234, 2345



      ]



   }



}

通知を処理する

ユーザーのユーザーID、個人情報 などのユーザーのストアにある個々の情報を保存する場合

サードパーティツールではなく、カスタムエンドポイントを使用して Webhook サーバーとして使用する場合、Webhook のペイロードからデータを削除することができ、自分のオートメーションソリューションを構築できます。次のコードサンプルは、例のソリューションを提供し、Roblox からのリクエストを検証することで、リプレイ攻撃を防止します

Extracting PII from Payload
const crypto = require('crypto')

const express = require('express');

let app = express();

app.use(express.json());

app.use(express.urlencoded({ extended: true }));

// This is a sample only code

app.all('/*', function (req, res) {

   console.log('-------- New Request Seen -------');

   // 1. Extract the timestamp and signature

   const shared_secret = '<Your secret>' // This can be set as an environment variable

   const hmac = crypto.createHmac('sha256', shared_secret)

   const roblox_signature_header = req.headers['roblox-signature'].split(',')

   // 'roblox-signature' is present in all requests:

   // Timestamp(t) is present in all requests, however signature value(v1) is not set unless a secret is shared during the webhook configuration.

   // Fetch header component at Index 0 -> 't=' and Index 1 -> 'v1='

   const timestamp = roblox_signature_header.find(e => e.startsWith('t=')).substring(2);

   const extracted_signature = roblox_signature_header.find(e => e.startsWith('v1='));

   // 2. Prevent Replay attack: 300 seconds window

   const request_timestamp_ms = timestamp * 1000;

   const window_time_ms = 300 * 1000

   const oldest_timestamp_allowed = Date.now() - window_time_ms;

   if (request_timestamp_ms < oldest_timestamp_allowed) {

      res.status(403).send('Expired Request')

   }

   // 3. Validate Signature

   if (extracted_signature !== undefined) {

      const signature_v1 = extracted_signature.substring(3);

      const message = `${timestamp}.${JSON.stringify(req.body)}`

      const base64_signature = hmac.update(message).digest('base64')

      if (signature_v1 !== base64_signature) {

         res.status(401).send('Unauthorized Request')

      }

   }

   // 4. Your logic to handle payload

   const payloadBody = req.body

   const eventType = payloadBody['EventType']

   if (eventType === 'RightToErasureRequest'){

      const userId = payloadBody['EventPayload']['UserId']

      const gameIds = payloadBody['EventPayload']['GameIds']

      const gameIdString = gameIds.toString()

      console.log(`The payload: UserId=${userId} and GameIds=${gameIdString}`)

      // If you store PII in data stores, use the UserId and GameIds to make a data store call to delete the information.

   }

   // 5. Return Response

   res.json({ message: 'Processed the message Successfully' });

})

app.listen(8080, function () {

   console.log('This is a Sample application')

})