ウェブフックの設定

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

イベント例：

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

ウェブフックのリスト

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

• 決済 — 注文が支払われたときに送信され、決済データおよび取引の詳細が含まれます。
• ご注文の決済が完了した — 決済ウェブフックが正常に処理されたときに送信され、購入したアイテムに関する情報とトランザクションIDが含まれます。ウェブフックのデータを使用して、ユーザーにアイテムを追加します。
• 返金 — 注文がキャンセルされたときに送信され、キャンセルされた決済データと取引の詳細が含まれます。
• 注文キャンセル — 返金ウェブフックが正常に処理されたときに送信され、購入したアイテムに関する情報とキャンセルされたトランザクションのIDが含まれています。購入した商品を削除するには、ウェブフックのデータを使用します。

• ユーザー検証 — ユーザーがゲームに登録されていることを確認するために、決済プロセスのさまざまな段階で送信されます。

以下は、このリストのウェブフックを使用してウェブサイト上で製品を購入し、返品するスキームです。

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

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

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

1. アドミンページでプロジェクトを開きます。
2. サイドメニューの「プロジェクト設定」をクリックし、「ウェブフック」タブに移動します。
3. 「ウェブフックサーバー」フィールドに、https://example.com形式でウェブフックを受信したいサーバーのURLを指定します。ウェブフックをテストするツールで見つけたURLを指定することもできます。
4. プロジェクトのウェブフックに署名するための秘密鍵がデフォルトで生成されます。新しい秘密鍵を生成したい場合は、更新アイコンをクリックします。
5. 「ウェブフックを有効にする」をクリックします。

1. アドミンページでプロジェクトを開きます。
2. サイドメニューで「プロジェクト設定」をクリックし、「ウェブフック」タブに移動します。
3. 「ウェブフックを無効にする」をクリックします。

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

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

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

• ストア
• 決済ソリューション

「ストア」タブで、以下のウェブフックをテストできます：

• 注文の支払いが完了しました（order_paid）
• 注文キャンセル（order_canceled）

テストするには：

1. ウェブフックテストブロックで、「ストア」タブに移動します。
2. ドロップダウンメニューで、アイテムのタイプを選択します。選択したタイプのアイテムがアドミンページで設定されていない場合、次のことをクリックします：
   • 接続する – このタイプのアイテムを持つモジュールが接続されていない場合
   • 構成する – 以前にモジュールを接続したが、セットアップを完了していない場合

1. ボタンをクリックすると、選択したアイテムのタイプに対応するアドミンページのセクションにリダイレクトされます。アイテムを作成したら、ウェブフックテストのセクションに戻り、次のステップに進みます。

3. エクソーラ注文IDフィールドに任意の値を入力します。
4. ドロップダウンリストからアイテムのSKUを選択し、数量を指定します。「+」をクリックして新しい行に追加することで、同じタイプのアイテムを複数選択できます。
5. 注文が支払われる通貨を選択します。
6. 「テスト」をクリックします。

指定されたデータを含む「ご注文の決済が完了した」と「注文キャンセル」のウェブフックが指定されたURLに送信されます。各ウェブフックタイプのテスト結果は、「テスト」ボタンの下に表示されます。

お知らせ

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

「決済ソリューション」タブで、以下のウェブフックをテストできます：

• ユーザー検証（user_validation）
• 支払い（payment）

テストするには：

1. テストセクションで、「決済ソリューション」タブに移動します。
2. 必要なフィールドに入力します：
   • ユーザーID — テストの際には、自由にアルファベットと数字の組み合わせを使用できます。
   • パブリックIユーザーID — メールアドレスやニックネームなど、ユーザーが知っているID。このフィールドは「ペイステーション > 設定 > 追加設定」セクションでプロジェクトでパブリックユーザーIDが有効になっている場合に表示されます。
   • 通貨 — ドロップダウンリストから通貨を選択します。
   • エクソーラインボイスID — エクソーラ側のトランザクションID。テストの際には、任意の数値を使用できます。
   • 金額 — 支払金額。テスト時には、任意の数値を使用できます。
   • インボイスID — ゲーム側のトランザクションID。テストの際には、自由にアルファベットと数字の組み合わせを使用できます。これは決済を成功させるための必須パラメータではありませんが、エクソーラ側のトランザクションIDとあなた側のトランザクションIDをリンクさせるために渡すことができます。
3. 「ウェブフックをテストする」をクリックします。

指定したURLに、データが入力されたウェブフックを受信します。各ウェブフックのテスト結果は、成功したシナリオとエラーが発生したシナリオの両方について、「テストウェブフック」ボタンの下に表示されます。プロジェクトでパブリックユーザーIDが有効になっている場合、ユーザー検索チェックの結果も表示されます。

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

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

ウェブフックリスナー

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

署名の生成

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

署名を生成するには：

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

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

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

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

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

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

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

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

決済ウェブフックの応答が受信されなかった場合、または5xxコードを含む応答を受け取った場合は、ウェブフックも時間間隔を空けて再送信されます。12時間以内に最大12回の試行が行われます。

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

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