ウェブフックをセットアップする
ウェブフックは、システムで発生したイベントの通知です。特定のイベントが発生すると、エクソーラはイベントデータを送信するHTTPリクエストをアプリケーションに送信します。これは通常JSON形式のPOST
リクエストです。
イベント例:
- アイテムカタログとのユーザーインタラクション
- 注文の支払いまたはキャンセル
ウェブフックのリスト
ゲームキーの販売には、ユーザー検証やアイテムのクレジットは必要ありません。支払いや注文のキャンセルなどのイベントに関する情報を受け取りたい場合は、ウェブフックを接続できます。
ウェブフックを接続する場合は、受信した必要なウェブフックをすべて処理することが重要です。
サイト上で商品を購入して返品する際には、エクソーラ側に2つのウェブフック受信オプションが設定されています。支払いと取引データを含む情報と購入した商品に関する情報は、別々に来ることも、1つのウェブフックにまとめることもできます。
ウェブフック受信オプションの詳細情報
組み込みのウェブフックで情報を受信します:
2025年1月22日以降にアドミンページでプロジェクトを作成した場合、注文支払い成功(order_paid
)と注文のキャンセル(order_canceled
)のウェブフックですべての情報を受け取ります。この場合、支払い(payment
)と返金(refund
)ウェブフックを処理する必要はありません。
個別のウェブフックで情報を受信します:
2025年1月22日以前にアドミンページでプロジェクトを作成した場合、以下のウェブフックを受け取ります:
- 支払いデータや取引の詳細に関する情報を含む支払い(
payment
)と返金(refund
)ウェブフック。 - 購入したアイテムに関する情報を含む注文支払い成功(
order_paid
)と注文のキャンセル(order_canceled
)ウェブフック。
すべての受信ウェブフックを処理する必要があります。
組み込みのウェブフックを受信する新しいオプションに切り替えるには、カスタマーサクセスマネージャーに連絡するか、csm@xsolla.comに電子メールを送信してください。
インゲームストアと決済管理を完全に操作するには、メインのウェブフックの処理を実装する必要があります:
アイテムカタログのパーソナライゼーションがアプリケーション側で実装されている場合は、パートナー側でカタログのパーソナライゼーションの処理を設定します。
アドミンページでのウェブフックのセットアップ
ウェブフックの受信を有効にするには:
- アドミンページでプロジェクトを開きます。
- サイドメニューの「プロジェクト設定」をクリックし、「ウェブフック」タブに移動します。
- 「ウェブフックサーバー」フィールドに、
https://example.com
形式でウェブフックを受信したいサーバーのURLを指定します。ウェブフックをテストするツールで見つけたURLを指定することもできます。
- プロジェクトのウェブフックに署名するための秘密鍵は、デフォルトで生成されます。新しい秘密鍵を生成したい場合は、更新アイコンをクリックします。
- 「ウェブフックを有効にする」をクリックします。
「ウェブフックサーバー」フィールドにURLを保存すると、「高度な設定」セクションが表示され、ウェブフックで詳細情報を受信するための権限を与えることができます。それを行うには、各権限の対応するトグルを「オン」に設定してください。各権限の行には、設定に影響を受けるウェブフックのリストが表示されます。
- アドミンページでプロジェクトを開きます。
- サイドメニューで「プロジェクト設定」をクリックし、「ウェブフック」タブに移動します。
- 「ウェブフックを無効にする」をクリックします。
アドミンページでのウェブフックをテストする
ウェブフックが正常にセットアップされると、ウェブフックセットアップブロックの下にウェブフックテストブロックが表示されます。
アドミンページのテストセクションは、ウェブフック受信オプションによって異なります。
組み込みのウェブフックを使用したシナリオのテストプロセスを以下に説明します。 「決済とストア」タブで、以下のウェブフックをテストできます:
テストするには:- ウェブフックテストセクションでは、「決済とストア」タブに移動します。
- ドロップダウンメニューで、「ゲームキー」を選択します。ゲームキーパッケージがアドミンページで設定されていない場合、次のいずれかのボタンが表示されます:
- 接続する – 「ゲームキー」モジュールが接続されていない場合
- 構成する – 以前にモジュールを接続したが、セットアップを完了していない場合
- 必要なフィールドを入力します:
- 「エクソーラ注文ID」フィールドに任意の値を入力します。
- ドロップダウンリストからゲームキーパッケージを選択します。
- ゲームパブリッシングプラットフォームを指定します。
- ユーザーID — テストの際には、自由にアルファベットと数字の組み合わせを使用できます。
- パブリックIユーザーID — メールアドレスやニックネームなど、ユーザーが知っているID。このフィールドは「ペイステーション > 設定」セクションでプロジェクトでパブリックユーザーIDが有効になっている場合に表示されます。
- エクソーラインボイスID — エクソーラ側のトランザクションID。テストの際には、任意の数値を使用できます。
- インボイスID — ゲーム側のトランザクションID。テストの際には、自由にアルファベットと数字の組み合わせを使用できます。これは決済を成功させるための必須パラメータではありませんが、エクソーラ側のトランザクションIDとあなた側のトランザクションIDをリンクさせるために渡すことができます。
- 金額 — 支払金額。テスト時には、任意の数値を使用できます。
- 通貨 — ドロップダウンリストから通貨を選択します。
- 「テストウェブフックをテスト」をクリックします。
各ウェブフックについて、成功したシナリオとエラーが発生したシナリオの両方を処理するように設定する必要があります。
ウェブフックリスナー
ウェブフックリスナーは、指定されたURLアドレスで受信したウェブフックを受信し、署名を生成し、エクソーラウェブフックサーバーに応答を送信できるようにするプログラムコードです。
署名の生成
ウェブフックを受信する場合、データ伝送のセキュリティを確保する必要があります。そのためには、ウェブフックのデータから署名を生成し、それがHTTPリクエストヘッダで送信された署名と一致することを検証する必要があります。
署名を生成するには:
- リクエスト本文のJSONとプロジェクトの秘密鍵を連結します。
- 最初のステップで取得した文字列にSHA-1暗号化ハッシュ関数を適用します。
ウェブフックへの応答の送信
ウェブフックの受信を確認するには、サーバーが以下のことを返す必要があります:
- 成功した応答の場合は
200
、201
、または204
HTTPコード。 - 指定されたユーザーが見つからなかったり、無効な署名が渡された場合、問題に関する説明が記載された
400
HTTPコードが表示されます。
ウェブフックハンドラーは、サーバーに一時的な問題が発生した場合に5xx
コードを返すこともあります。
エクソーラサーバーが「注文支払い成功」と「注文のキャンセル」のウェブフックで応答を受信しなかった場合、または5xx
コードの応答を受信した場合、以下のスケジュールでウェブフックを再送信します:
- 5分間隔で2回再試行
- 15分間隔で7回再試行
- 60分間隔で10回再試行
ウェブフックの送信は、最初の試行から12時間以内に最大20回まで試行されます。
エクソーラサーバーが決済ウェブフックまたは返金ウェブフックに対して応答を受信しない場合、または応答を受信した5xx
コード、ウェブフックも時間間隔が長くなって再送される12時間以内に最大12回の試行が行われます。
エクソーラサーバーがユーザー検証ウェブフックに対する応答が受信されなかった場合、400
または5xx
のコードを含む応答が受信された場合、ユーザー検証ウェブフックは再送信されません。
この場合、ユーザーにはエラーが表示され、「決済」と「ご注文の決済が完了した」のウェブフックは送信されません。
誤字脱字などのテキストエラーを見つけましたか? テキストを選択し、Ctrl+Enterを押します。