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

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

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

イベント例

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

ウェブフックのリスト

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

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

お知らせ

サイト上で商品を購入して返品する際には、エクソーラ側に2つのウェブフック受信オプションが設定されています。支払いと取引データを含む情報と購入した商品に関する情報は、別々に来ることも、1つのウェブフックにまとめることもできます。

ウェブフック受信オプションの詳細情報

組み込みのウェブフックで情報を受信します:

2025年1月22日以降にアドミンページでプロジェクトを作成した場合、注文支払い成功order_paid)と注文のキャンセルorder_canceled)のウェブフックですべての情報を受け取ります。この場合、支払いpayment)と返金refund)ウェブフックを処理する必要はありません。

個別のウェブフックで情報を受信します:

2025年1月22日以前にアドミンページでプロジェクトを作成した場合、以下のウェブフックを受け取ります:

すべての受信ウェブフックを処理する必要があります。

組み込みのウェブフックを受信する新しいオプションに切り替えるには、カスタマーサクセスマネージャーに連絡するか、csm@xsolla.comに電子メールを送信してください。

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

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

お知らせ
実際に支払いを受けるには、「決済」、「ご注文の決済が完了した」と「ユーザー検証」ウェブフックを実装し、ライセンス契約に署名するだけで済みます。
お知らせ
ウェブフックを使う代わりに、PlayFab統合を使って決済情報や注文キャンセル情報を受け取ることができます。

アドミンページでのウェブフックのセットアップ

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

  1. アドミンページでプロジェクトを開きます。
  2. サイドメニューの「プロジェクト設定」をクリックし、「ウェブフック」タブに移動します。
  3. ウェブフックサーバー」フィールドに、https://example.com形式でウェブフックを受信したいサーバーのURLを指定します。ウェブフックをテストするツールで見つけたURLを指定することもできます。

注意
データ転送にはHTTPSプロトコルが使用されます。HTTPプロトコルはサポートされていません。
  1. プロジェクトのウェブフックに署名するための秘密鍵は、デフォルトで生成されます。新しい秘密鍵を生成したい場合は、更新アイコンをクリックします。
  2. ウェブフックを有効にする」をクリックします。

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

お知らせ
ウェブフックをテストするには、webhook.siteなどの専用サイトや、ngrokなどのプラットフォームを選択することもできます。
注意
同時に異なるURLにウェブフックを送信することはできません。アドミンページでは、まずテスト用のURLを指定してから、実際のURLに置き換えることができます。
ウェブフックの受信を無効にするには:
  1. アドミンページでプロジェクトを開きます。
  2. サイドメニューで「プロジェクト設定」をクリックし、「ウェブフック」タブに移動します。
  3. ウェブフックを無効にする」をクリックします。

アドミンページでのウェブフックをテストする

ウェブフックが正常にセットアップされると、ウェブフックセットアップブロックの下にウェブフックテストブロックが表示されます。

アドミンページのテストセクションは、ウェブフック受信オプションによって異なります。

組み込みのウェブフックを使用したシナリオのテストプロセスを以下に説明します。 「決済とストア」タブで、以下のウェブフックをテストできます:

テストするには:

  1. ウェブフックテストセクションでは、「決済とストア」タブに移動します。
  2. ドロップダウンメニューで、「ゲームキー」を選択します。ゲームキーパッケージがアドミンページで設定されていない場合、次のいずれかのボタンが表示されます:
    • 接続する – 「ゲームキー」モジュールが接続されていない場合
    • 構成する – 以前にモジュールを接続したが、セットアップを完了していない場合
  3. 必要なフィールドを入力します:
    1. エクソーラ注文ID」フィールドに任意の値を入力します。
    2. ドロップダウンリストからゲームキーパッケージを選択します。
    3. ゲームパブリッシングプラットフォームを指定します。
    4. ユーザーID — テストの際には、自由にアルファベットと数字の組み合わせを使用できます。
    5. パブリックIユーザーID — メールアドレスやニックネームなど、ユーザーが知っているID。このフィールドは「ペイステーション > 設定」セクションでプロジェクトでパブリックユーザーIDが有効になっている場合に表示されます。
    6. エクソーラインボイスID — エクソーラ側のトランザクションID。テストの際には、任意の数値を使用できます。
    7. インボイスID — ゲーム側のトランザクションID。テストの際には、自由にアルファベットと数字の組み合わせを使用できます。これは決済を成功させるための必須パラメータではありませんが、エクソーラ側のトランザクションIDとあなた側のトランザクションIDをリンクさせるために渡すことができます。
    8. 金額 — 支払金額。テスト時には、任意の数値を使用できます。
    9. 通貨 — ドロップダウンリストから通貨を選択します。
  4. テストウェブフックをテスト」をクリックします。
ユーザー検証、指定されたデータを含む「注文支払い成功」と「注文のキャンセル」のウェブフックが指定されたURLに送信されます。各ウェブフックタイプのテスト結果は、「テスト」ボタンの下に表示されます。 プロジェクトでパブリックユーザーIDが有効になっている場合、ユーザー検索チェックの結果も表示されます。

各ウェブフックについて、成功したシナリオとエラーが発生したシナリオの両方を処理するように設定する必要があります。

お知らせ
テストに合格しなかったことを示すエラーメッセージがテストブロックに表示された場合は、ウェブフックリスナーのウェブフック応答設定を確認してください。これらのエラーに関する情報は、テスト結果に記載されています。

ウェブフックリスナー

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

署名の生成

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

署名を生成するには:

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

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

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

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

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

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

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

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

エクソーラサーバーが決済ウェブフックまたは返金ウェブフックに対して応答を受信しない場合、または応答を受信した5xxコード、ウェブフックも時間間隔が長くなって再送される12時間以内に最大12回の試行が行われます。

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

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

お知らせ
ウェブフックの完全なリストとメカニズム、およびその処理の詳細な事例については、ウェブフックドキュメンテーションに記載されています。
この記事は役に立ちましたか?
ありがとうございます!
改善できることはありますか? メッセージ
申し訳ありません
この記事が参考にならなかった理由を説明してください。 メッセージ
ご意見ありがとうございました!
あなたのメッセージを確認し、体験を向上させるために利用させていただきます。
最終更新日: 2025年1月23日

誤字脱字などのテキストエラーを見つけましたか? テキストを選択し、Ctrl+Enterを押します。

問題を報告する
当社は常にコンテンツを見直しています。お客様のご意見は改善に役立ちます。
フォローアップ用のメールをご提供してください
ご意見ありがとうございました!