ウェブフックをセットアップする

ウェブフックは、システムで発生したイベントの通知です。特定のイベントが発生すると、エクソーラはイベントデータを送信するHTTPリクエストをアプリケーションに送信します。これは通常JSON形式のPOSTリクエストです。

イベント例：

• アイテムカタログとのユーザーインタラクション
• 注文の支払いまたはキャンセル

ウェブフックのリスト

ゲームキーの販売には、ユーザー検証やアイテムのクレジットは必要ありません。支払いや注文のキャンセルなどのイベントに関する情報を受け取りたい場合は、ウェブフックを接続できます。

ウェブフックを接続する場合は、受信した必要なウェブフックをすべて処理することが重要です。

インゲームストアと決済管理を完全に操作するには、メインのウェブフックの処理を実装する必要があります：

以下のスキームは、集約ウェブフックを使用してアイテムを購入して返品するプロセスを示しています。

  sequenceDiagram
    participant User
    participant GameClient as Game Client
    participant Xsolla
    participant GameServer as Game Server
    %% Item Purchase
        Note over User, GameServer: Item purchase
        User ->> GameClient: Logs in
        GameClient ->> Xsolla: Sends user authentication request
        Xsolla -->> GameClient: Returns JWT / OAuth 2.0 token
        GameClient ->> Xsolla: Sends JWT, project ID, pagination parameters
        Xsolla -->> GameClient: Returns array of items
        GameClient -->> User: Displays storefront
        User ->> GameClient: Selects item and clicks Buy
        GameClient ->> Xsolla: Creates order request
        Xsolla -->> GameClient: Returns payment token
        GameClient ->> Xsolla: Opens payment UI URL with received token
        Xsolla ->> GameServer: Sends User validation webhook
        GameServer -->> Xsolla: Returns success status code
        Xsolla -->> User: Displays payment UI
        User ->> Xsolla: Chooses payment method and clicks Pay
        Xsolla ->> GameServer: Sends Successful payment for order webhook
        GameServer ->> GameServer: Grants purchases to user
        GameServer -->> Xsolla: Returns success status code
        Xsolla -->> User: Shows successful purchase screen
    %% Refund / Chargeback
        Note over User, GameServer: Refund / Chargeback
        User ->> Xsolla: Requests refund or chargeback
        Xsolla ->> GameServer: Sends Order cancellation webhook
        GameServer ->> GameServer: Removes items from user inventory
        GameServer -->> Xsolla: Returns success status code
        Xsolla -->> User: Refunds the payment

アイテムカタログのパーソナライゼーションがアプリケーション側で実装されている場合は、パートナー側でカタログのパーソナライゼーションの処理を設定します。

パブリッシャーアカウントでのウェブフックのセットアップ

ウェブフックの受信を有効にするには：

1. パブリッシャーアカウント内のプロジェクトで、設定 >ウェブフックセクションに移動します。
2. ウェブフックサーバーフィールドに、ウェブフックを受信したいサーバーのURLをhttps://example.com形式で指定します。ウェブフックテストツールで見つけたURLを指定することもできます。

3. プロジェクトのウェブフックに署名するための秘密鍵は、デフォルトで生成されます。新しい秘密鍵を生成したい場合は、更新アイコンをクリックします。
4. 「ウェブフックを有効にする」をクリックします。

「ウェブフックサーバー」フィールドにURLを保存すると、詳細設定セクションが表示され、ウェブフックで詳細情報を受信するための権限を与えることができます。これを行うには、必要なトグルを「アクティブ」に設定します。各権限の行には、設定に影響を受けるウェブフックのリストが表示されます。

1. パブリッシャーアカウント内のプロジェクトで、設定 >ウェブフックセクションに移動します。
2. 「ウェブフックを無効にする」をクリックします。

パブリッシャーアカウントでのウェブフックをテストする

プロジェクトでウェブフックを有効化すると、パブリッシャーアカウント内の詳細設定の下に、ウェブフックをテストするためのセクションが表示されます。

次のウェブフックをテストできます：

ウェブフックをテストするには：

1. ウェブフックテストセクションでは、「決済ソリューションとストア」タブに移動します。
2. ドロップダウンメニューからゲームキーを選択します。プロジェクト内にゲームキーパッケージが設定されていない場合は、設定画面へ移動するためのボタンが表示されます。
3. 必要なフィールドを記入します：
   • エクソーラ注文ID — エクソーラ側の注文IDです。テスト時は任意の数値を入力できます。
   • エクソーラ請求書IDは、エクソーラ側のトランザクションIDです。テスト時は任意の数値を入力できます。
   • アイテム — ウェブフックで情報を受け取りたいアイテムを指定します。ドロップダウンリストからアイテムのSKUを選択し、数量を入力してください。「+」をクリックして新しい行を追加することで、同じタイプのアイテムを複数選択できます。
   • ユーザーID — テスト時は、任意の英数字の組み合わせを使用できます。
   • インボイスID — ゲーム側でのトランザクションIDです。テスト時は任意の英数字の組み合わせを使用できます。これは決済を正常に完了させるための必須パラメータではありませんが、これを渡すことで、ゲーム側のトランザクションIDとエクソーラ側のトランザクションIDを紐付けることができます。
   • 金額 — 決済金額です。テスト時は任意の数値を入力できます。
   • 通貨 — ドロップダウンリストから通貨を選択します。
4. 「テストウェブフックをテスト」をクリックします。

注文支払い完了、注文のキャンセルおよびユーザー検証に関するウェブフックが、指定されたデータとともに、提供されたURLに送信されます。各ウェブフックタイプのテスト結果は、「ウェブフックをテスト」ボタンの下に表示されます。各ウェブフックについて、「成功」と「エラー」の両方のシナリオの処理を構成する必要があります。

ウェブフックリスナー

ウェブフックリスナーは、指定されたURLアドレスで受信したウェブフックを受信し、署名を生成し、エクソーラウェブフックサーバーに応答を送信できるようにするプログラムコードです。

署名の生成

ウェブフックを受信する場合、データ伝送のセキュリティを確保する必要があります。そのためには、ウェブフックのデータから署名を生成し、それがHTTPリクエストヘッダで送信された署名と一致することを検証する必要があります。

署名を生成するには：

1. リクエスト本文のJSONとプロジェクトの秘密鍵を連結します。
2. 最初のステップで取得した文字列にSHA-1暗号化ハッシュ関数を適用します。

ウェブフックへの応答の送信

ウェブフックの受信を確認するには、サーバーが以下のことを返す必要があります：

• 成功した応答の場合は200、201、または204 HTTPコード。
• 指定したユーザーが見つからなかったり、無効な署名が渡された場合、問題に関する説明が記載された400 HTTPコードが表示されます。

ウェブフックハンドラーは、サーバーに一時的な問題が発生した場合に5xxコードを返すこともあります。

エクソーラサーバーが「注文支払い完了」と「注文のキャンセル」のウェブフックで応答を受信しなかった場合、または5xxコードの応答を受信した場合、以下のスケジュールでウェブフックを再送信します：

• 5分間隔で2回再試行
• 15分間隔で7回再試行
• 60分間隔で10回再試行

ウェブフックの送信は、最初の試行から12時間以内に最大20回まで試行されます。

決済および返金のウェブフックにおけるリトライロジックについては、それぞれのウェブフック詳細ページに記載されています。

エクソーラサーバーがユーザー検証ウェブフックに対する応答が受信されなかった場合、400または5xxのコードを含む応答が受信された場合、ユーザー検証ウェブフックは再送信されません。

この場合、ユーザーにはエラーが表示され、「決済」と「注文支払い完了」のウェブフックは送信されません。