Xsolla-logo

概要

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

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

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

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

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

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

支払い処理ウェブフック

サーバー側をセットアップする

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

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

通知

リスナーが既存のトランザクションIDを持つウェブフックを受信した場合、そのトランザクションの以前の結果を返す必要があります。ユーザーに2回請求したり、データベースに重複したレコードを作成することは推奨されません。

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

エクソラAPIは、成功したリクエストと失敗したリクエストに対して従来のHTTP応答コードを受け入れます。コード204は、処理が成功したことを示します。

インターネット接続は常に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"
    }
}

ウェブフック一覧

通知タイプはnotification_typeパラメータで送信されます。

ウェブフック 製品/ソリューション 通知タイプ 説明
ユーザーの検証 決済ステーション 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 注文がキャンセルされたときに送信されます。