Xsolla-logo

Overview

Webhooks allow you to receive instant notifications of configured events that happen on Xsolla’s side. You can use webhooks to automate back-end and supplementary functions of your application.

Examples of events that you can be notified about:

  • payments, including purchases of virtual currency and items
  • recurring payments and actions with subscriptions
  • refunds

When a configured event occurs, Xsolla notifies your system about it via webhooks. For example, you can do the following after receiving a webhook:

  • add to a user’s balance
  • unlock new items for a user
  • start subscription service
  • block user after fraud detection

Below is an example of how a payment processing webhook works:

Payment processing webhook

Set up server side

The following settings have to be applied for webhooks to work correctly:

  • Listen to webhooks at the following IP addresses: 185.30.20.0/24, 185.30.21.0/24, 185.30.23.0/24.
  • Application database must not contain two successful transactions with the same ID.

Notice

If your listener receives a webhook with an existing transaction ID, it must return the previous result for that transaction. It is not recommended to charge the user twice or create duplicate records in the database.

  • A created signature has to match the one passed in the HTTP header.
  • In case of an error, return code 400 (e.g., when a required parameter is missing or a recharge has failed). For temporary errors with your servers, use code 500.

Note

Xsolla API accepts conventional HTTP response codes for successful and failed requests. Code 204 indicates successful processing.

As internet connections are not always 100% reliable, webhooks may be lost or delayed. To address this issue, Xsolla resends failed webhooks until your listener receives them. Webhook resends are sent within 12 hours after the previous one until your listener confirms receiving. The maximum number of retries is 12.

Note

Although connection problems may result in lost, delayed, or duplicate webhooks, the most common cause is incorrect logic on the listener side.

Sign requests

Digital signatures enable secure data transmission. To generate a signature:

  1. Concatenate the request’s JSON body with your project’s secret key.
  2. Apply SHA-1 hashing to the resulting string.
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"
      }
    }'

Errors

Error codes for HTTP code 400:

Code Message
INVALID_USER Invalid user
INVALID_PARAMETER Invalid parameter
INVALID_SIGNATURE Invalid signature
INCORRECT_AMOUNT Incorrect amount
INCORRECT_INVOICE Incorrect invoice
HTTP/1.1 400 Bad Request
{
    "error":{
        "code":"INVALID_USER",
        "message":"Invalid user"
    }
}

Webhooks list

Note

The notification type is sent in the notification_type parameter.

Webhook Product/Solution Notification type Description
User validation Pay Station user_validation Sent to check if a user exists in the game.
User search Pay Station user_search Sent to get user info based on public user ID.
Payment Pay Station, Subscriptions payment Sent when a user completes a payment.
Refund Pay Station, Subscriptions refund Sent when a payment must be canceled for any reason.
Partial refund Pay Station partial_refund Sent when a payment must be partially canceled for any reason.
AFS rejected transaction Pay Station afs_reject Sent when a transaction is declined during an AFS check.
AFS updated blocklist Pay Station afs_black_list Sent when the AFS blocklist is updated.
Created subscription Subscriptions create_subscription Sent when a user creates a subscription.
Updated subscription Subscriptions update_subscription Sent when a subscription is renewed or changed.
Canceled subscription Subscriptions cancel_subscription Sent when a subscription is canceled.
Nonrenewing subscription Subscriptions non_renewal_subscription Sent when status is set to nonrenewing.
Get game keys Buy Button get_pincode Sent when Xsolla API needs to obtain the game keys.
User balance: Manual update In-Game Store user_balance_operation Sent when a user balance changes manually. Operation type — internal.
User balance: Payment In-Game Store user_balance_operation Sent when a user makes payment. Operation type — payment.
User balance: Refund In-Game Store user_balance_operation Sent when a user cancels payment. Operation type — cancellation.
User balance: Redeem coupon In-Game Store user_balance_operation Sent when a user redeems a coupon to receive virtual items or virtual currency in a game. Operation type — coupon.
User balance: Purchase In-Game Store user_balance_operation Sent when a user makes purchase in a game. Operation type — inGamePurchase.
Get friends Buy Button friends_list Sent when a user sends a request for their list of friends.
Activate key Buy Button redeem_key Sent when a user activates a key.
Upgrade refund Buy Button upgrade_refund Sent when the upgrade is cancelled.
Add payment account Pay Station payment_account_add Sent when a user adds or saves a payment account.
Remove payment account Pay Station payment_account_remove Sent when a user removes the payment account from saved accounts.
User validation in Web Shop Web Shop - Sent from a Web Shop site to check if a user exists in the game.
Payout transaction completion Payouts - Sent to notify that payout transaction was successfully completed.
Catalog personalization on partner’s side In-Game Store partner_side_catalog Sent when a user interacts with the store.