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 ステータスが非更新に設定される場合に送信されます。
ゲームキーを取得 get_pincode エクソラAPIがゲームキーを取得する必要がある場合に送信されます。
ユーザー残高:手動更新 user_balance_operation ユーザーバランスが手動で変更された場合に送信されます。操作タイプ— internal
ユーザー残高:決済 user_balance_operation ユーザーが支払いを行う場合に送信されます。操作タイプ— payment
ユーザー残高:返金 user_balance_operation ユーザーが支払いをキャンセルした場合に送信されます。操作タイプ— cancellation
ユーザー残高:クーポンを引き換える user_balance_operation ユーザーがクーポンを利用して、ゲーム内の仮想アイテムまたは仮想通貨を受け取る場合に送信されます。操作タイプ— coupon
ユーザー残高:購入 user_balance_operation ユーザーがゲームで購入した場合に送信されます。操作タイプ— inGamePurchase
友達を取得 friends_list ユーザーが友達リストのリクエストを送信した場合に送信されます。
キーをアクティブにする redeem_key ユーザーがキーを有効にする場合に送信されます。
返金を更新 upgrade_refund アップグレードがキャンセルされた場合に送信されます。
決済アカウントを追加 payment_account_add ユーザーが支払いアカウントを追加または保存した場合に送信されます。
支払いアカウントを削除 payment_account_remove ユーザーが保存済みアカウントから決済アカウントを削除する場合に送信されます。