ウェブフックを使用すると、エクソラ側で発生した構成済みイベントの即時通知を受信できます。ウェブフックを使用して、アプリケーションのバックエンドおよび補足機能を自 動化することができます。

通知可能なイベントの例：

• お支払い、仮想通貨やアイテムの購入を含む
• 継続払いとサブスクリプションによるアクション
• 返金

構成されたイベントが発生すると、エクソラはウェブフックを介してそのことをシステムに通知します。たとえば、ウェブフックを受信した後、次の操作を実行できます：

• ユーザーの残高に追加する
• ユーザーの新しいアイテムのロックを解除する
• サブスクリプションサービスを開始する
• 不正検出後にユーザーをブロックする

以下は、支払い処理ウェブフックの動作事例です：

ウェブフックを正しく機能させるには、次の設定を適用する必要があります：

• 以下のIPアドレスのウェブフックをリッスンします: 185.30.20.0/24、185.30.21.0/24、185.30.23.0/24。
• アプリケーションデータベースには、同じIDを持つ2つの成功したトランザクションが含まれていてはなりません。

• 作成された署名は、HTTPヘッダーで渡されたものと一致する必要があります。
• エラーが発生した場合は、コード400を返します（たとえば、必須パラメータがない場合、リチャージに失敗した場合など）。サーバーの一時的なエラーについては、コード500を使用してください。

インターネット接続は常に100％信頼できるとは限らないため、ウェブフックが失われたり遅延したりする可能性があります。この問題に対処するために、エクソラは、リスナ ーがウェブフックを受信するまで、失敗したウェブフックを再送信します。ウェブフックの再送信は、リスナーが受信を確認するまで、前回の送信から12時間以内に行われます 。再試行の最大回数は12回です。

デジタル署名により、安全なデータ送信が可能になります。署名を生成するには：

1. リクエストのJSON本文をプロジェクトの秘密鍵と連結します。
2. 結果の文字列にSHA-1ハッシュを適用します。

POST /your_uri HTTP/1.1
Host: your.host
Accept: application/json
Content-Type: application/json
Content-Length: 165
Authorization: Signature 52eac2713985e212351610d008e7e14fae46f902
{
  "notification_type":"user_validation",
  "user":{
      "ip":"127.0.0.1",
      "phone":"18777976552",
      "email":"email@example.com",
      "id":1234567,
      "name":"Xsolla User",
      "country":"US"
  }
}

curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Authorization: Signature 52eac2713985e212351610d008e7e14fae46f902' \
-d '{
  "notification_type":
    "user_validation",
    "user":
      {
        "ip": "127.0.0.1",
        "phone": "18777976552",
        "email": "email@example.com",
        "id": 1234567,
        "name": "Xsolla User",
        "country": "US"
      }
    }'

HTTPコード400のエラーコード：

コード	メッセージ
INVALID_USER	無効なユーザー
INVALID_PARAMETER	無効なパラメータ
INVALID_SIGNATURE	無効な署名です
INCORRECT_AMOUNT	不正確な数量
INCORRECT_INVOICE	不正確なインボイス

HTTP/1.1 400 Bad Request
{
    "error":{
        "code":"INVALID_USER",
        "message":"Invalid user"
    }
}

ウェブフック	製品/ソリューション	通知タイプ	説明
ユーザーの検証	決済ステーション	user_validation	ユーザーがゲーム内に存在するかどうかを確認するために送信されます。
ユーザー検索	決済ステーション	user_search	パブリックユーザーIDに基づいてユーザー情報を取得するために送信されます。
決済	決済ステーション、サブスクリプション	payment	ユーザーが決済を完了した場合に送信されます。
返金	決済ステーション、サブスクリプション	refund	何らかの理由で決済をキャンセルする必要がある場合に送信されます。
一部返金	決済ステーション	partial_refund	何らかの理由で決済を一部キャンセルする必要がある場合に送信されます。
AFSの拒否された取引	決済ステーション	afs_reject	AFSチェック中にトランザクションが拒否されると、エクソラはトランザクションの詳細をURLウェブフックに送信されます。
AFSの更新されたブロックリスト	決済ステーション	afs_black_list	AFSブロックリストが更新される場合に送信されます。
作成されたサブスクリプション	サブスクリプション	create_subscription	ユーザーがサブスクリプションを作成する場合に送信されます。
更新されたサブスクリプション	サブスクリプション	update_subscription	サブスクリプションが更新または変更された場合に送信されます。
キャンセルされたサブスクリプション	サブスクリプション	cancel_subscription	サブスクリプションがキャンセルされた場合に送信されます。
非更新サブスクリプション	サブスクリプション	non_renewal_subscription	ステータスが非更新に設定される場合に送信されます。
ゲームキーを取得	Buy Button	get_pincode	エクソラAPIがゲームキーを取得する必要がある場合に送信されます。
ユーザー残高：手動更新	ゲーム内ストア	user_balance_operation	ユーザーバランスが手動で変更された場合に送信されます。操作タイプ— internal。
ユーザー残高：決済	ゲーム内ストア	user_balance_operation	ユーザーが支払いを行う場合に送信されます。操作タイプ— payment。
ユーザー残高：返金	ゲーム内ストア	user_balance_operation	ユーザーが支払いをキャンセルした場合に送信されます。操作タイプ— cancellation。
ユーザー残高：クーポンを引き換える	ゲーム内ストア	user_balance_operation	ユーザーがクーポンを利用して、ゲーム内の仮想アイテムまたは仮想通貨を受け取る場合に送信されます。操作タイプ— coupon。
ユーザー残高：購入	ゲーム内ストア	user_balance_operation	ユーザーがゲームで購入した場合に送信されます。操作タイプ— inGamePurchase。
キーをアクティブにする	Buy Button	redeem_key	ユーザーがキーを有効にする場合に送信されます。
決済アカウントを追加	決済ステーション	payment_account_add	ユーザーが支払いアカウントを追加または保存した場合に送信されます。
支払いアカウントを削除	決済ステーション	payment_account_remove	ユーザーが保存済みアカウントから決済アカウントを削除する場合に送信されます。
ウェブショップでのユーザー検証	ウェブショップ	-	ウェブショップのサイトから送信され、ゲーム内にユーザーが存在するかどうかを確認します。
ペイアウトトランザクション処理中	ペイアウト	-	ペイアウトのトランザクションが作成され、処理中であることを通知するために送信されます。
ペイアウトトランザクションの完了	ペイアウト	-	ペイアウトが正常に完了したことを通知するために送信されます。
パートナー側でのカタログパーソナライゼーション	ゲーム内ストア	partner_side_catalog	ユーザーがストアと直接交信する時に送信されます。
注文支払い完了	ゲーム内ストア	order_paid	注文が支払われたときに送信されます。
注文のキャンセル	ゲーム内ストア	order_canceled	注文がキャンセルされたときに送信されます。