Webhooks are notifications about events occurring in the system. When a specific event occurs, Xsolla sends an HTTP request, in which event data is transmitted, to your application. This is usually a POST request in JSON format.

Event examples:

• user interaction with an item catalog
• payment or cancellation of an order

When a set event happens, Xsolla notifies your system about it via a webhook. As a result, you can perform actions such as:

• replenish the user's balance
• make a payment refund
• credit or debit new items from the user account
• start providing a subscription
• block a user in case of a suspicion of fraud

Example of a payment processing webhook workflow:

Video guide for Xsolla webhooks integration:

Webhooks settings when working with Xsolla products and solutions:

If you use products and solutions that require working with webhooks, enable and test the webhooks in your Publisher Account and set up their processing. When specific events occur, webhooks are sent sequentially. Therefore, if you do not process one of the webhooks, subsequent webhooks will not be sent. The list of required webhooks is presented below.

2 webhook sending options have been set up on Xsolla’s side when purchasing and returning items on the site — information with payment and transaction data and information about purchased items can come separately or can be combined into one webhook.

Receiving information in combined webhooks:

If you registered in Publisher Account after January 22, 2025, you receive all the information in the Successful payment for order (order_paid) and Order cancellation (order_canceled) webhooks. In this case, you do not need to process the Payment (payment) and Refund (refund) webhooks.

Receiving information in separate webhooks:

If you registered in Publisher Account on or before January 22, 2025, you receive the following webhooks:

• Payment (payment) and Refund (refund) with information about payment data and transaction details.
• Successful payment for order (order_paid) and Order cancellation (order_canceled) with information about purchased items.

You need to process all incoming webhooks. To switch to the new option with receiving combined webhooks, contact your Customer Success Managers or email to csm@xsolla.com.

For the full operation of the in-game store and payment management, it is necessary to implement the processing of the main webhooks.

If you receive combined webhooks:

If you receive separate webhooks:

If item catalog personalization is implemented on your application’s side, set up processing of Catalog personalization on the partner’s side webhook.

To automatically manage subscription plans, it is necessary to implement processing of the main webhooks:

• User validation (user_validation) — is sent at different stages of the payment process to ensure the user is registered in the game.
• Payment (payment) — is sent when an order is paid and contains payment data and transaction details.
• Created subscription (create_subscription) — is sent when a Payment webhook has been successfully processed or the user has purchased a subscription with a trial period. It contains the details of the purchased subscription and user data. Use the webhook data to add a subscription to the user.
• Updated subscription (update_subscription) — is sent when a subscription is renewed or changed, when a Payment webhook has been successfully processed. It contains the details of the purchased subscription and user data. Use the webhook data to extend the user's subscription or change the subscription parameters.
• Refund (refund) — is sent when an order is canceled and contains the canceled payment data and transaction details.
• Canceled subscription (cancel_subscription) — is sent when a Refund webhook has been successfully processed or the subscription was canceled for another reason. It contains information about the subscription and user data. Use the webhook data to deduct purchased subscriptions from the user.

To enable receiving webhooks:

1. In the project in Publisher Account go to Project Settings > Webhooks section.
2. In the Webhook server field, specify the URL of your server where you want to receive webhooks in the https://example.com format. You can also specify the URL you find in a tool for testing webhooks.

3. A secret key to sign project webhooks is generated by default. If you want to generate a new secret key, click the refresh icon.
4. Click Enable webhooks.

To disable receiving webhooks:

1. In the project in Publisher Account go to Project Settings > Webhooks section.
2. Click Disable webhooks.

For the webhooks in the Payments and Store section, advanced settings are available. They will automatically appear under the General settings block after you click the Get webhooks button.

In this section, you can set up the receipt of additional information in webhooks. To do this, set the corresponding switches to the active position. The line of each permission indicates the webhooks that will be affected by changing the settings.

Testing webhooks helps to ensure the correct setup of the project both on your side and on Xsolla side.

If webhooks are set up successfully, a webhooks testing section is displayed below the webhooks setup section.

The testing section in the Publisher Account varies depending on the webhook receiving option.

If you receive combined webhooks:

If you receive separate webhooks:

The process of testing for the scenario with combined webhooks is described below.

In the Payments and Store tab, you can test the following webhooks:

• User validation (user_validation)
• Successful payment for order (order_paid)
• Order cancellation (order_canceled)

To test:

1. In the webhooks testing section, go to the Payments and Store tab.

2. In the drop-down menu, select the type of item. If the item of selected type is not set up in Publisher Account, click:

   • Connect – if the module with items of this type is not connected
   • Configure – if you connected the module previously, but have not completed the setup
     When you click the button, you will be redirected to the section of Publisher Account corresponding to the type of the selected item. After creating the item, return to the webhook testing section and proceed to the next step.

3. Fill in the necessary fields:

   1. Select the items’ SKU from the drop-down list and indicate the amount. You can choose multiple items of the same type by clicking + and adding them in a new line.
   2. User ID — when testing, you can use any combination of letters and digits.
   3. Public user ID — ID known to a user, e.g., an email or a nickname. This field is displayed if public user ID is enabled in your project in the Pay Station > Settings.
   4. Enter any value in the Xsolla Order ID field.
   5. Xsolla Invoice ID — transaction ID on Xsolla side. When testing, you can use any numeric value.
   6. Invoice ID — transaction ID on your game’s side. When testing, you can use any combination of letters and digits. It is not a required parameter for a successful payment, but you can pass it to link the transaction ID on your side to the transaction ID on Xsolla side.
   7. Amount — payment amount. When testing, you can use any numeric value.
   8. Currency — select a currency from the drop-down list.

4. Click Test webhooks.

User validation, Successful payment for order and Order cancellation webhooks with the specified data are sent to the provided URL. The results of testing each webhook type are displayed below the Test webhooks button.

If public user ID is enabled in your project, you will also see the results of a user search check.

For each webhook, you need to configure processing both scenarios: a successful one and the one with an error.

In the Subscriptions tab, you can test the following webhooks:

• User validation (user_validation)
• Payment (payment)

To test:

1. In the testing section, go to the Subscriptions tab.
2. Fill in the necessary fields:
   1. User ID — when testing, you can use any combination of letters and digits.
   2. Xsolla Invoice ID — transaction ID on Xsolla side. When testing, you can use any numeric value.
   3. Public user ID — ID known to a user, e.g., an email or a nickname. This field is displayed if public user ID is enabled in your project in the Pay Station > Settings > Additional settings section.
   4. Currency — select a currency from the drop-down list.
   5. Plan ID — a subscription plan. Choose a plan from the drop-down list.
   6. Subscription product — choose a product from the drop-down list (optional).
   7. Amount — payment amount. When testing, you can use any numeric value.
   8. Invoice ID — transaction ID on your game’s side. When testing, you can use any combination of letters and digits. It is not a required parameter for a successful payment, but you can pass it to link the transaction ID on your side to the transaction ID on Xsolla side.
   9. Trial period. To test the purchase of a subscription without a trial period or to test the renewal of a subscription, specify the value 0.
3. Click Test webhooks.

In the specified URL, you will receive webhooks with filled in data. Testing results of each webhook, for both a successful scenario and a scenario with an error, are displayed under the Test webhooks button.

Webhook listener is program code that allows receiving incoming webhooks at a specified URL address, generating a signature, and sending a response to the Xsolla webhook server.

On the your application side, implement the reception of webhooks from the following IP addresses: 185.30.20.0/24, 185.30.21.0/24, 185.30.23.0/24, 34.102.38.178, 34.94.43.207, 35.236.73.234, 34.94.69.44, 34.102.22.197.

Limitations:

• There should not be multiple successful transactions with the same ID in your application's database.
• If the webhook listener received a webhook with an ID that already exists in the database, you need to return the result of the previous processing of this transaction. It is not recommended to credit the user with a duplicate purchase and create duplicate records in the database.

When receiving a webhook, you should ensure the security of data transmission. To achieve this, a signature must be generated from the webhook data and verified that it matches the signature sent in the HTTP request header. To generate a signature:

1. Concatenate the JSON from the request body and the project’s secret key.
2. Apply the SHA-1 cryptographic hash function to the string obtained in the first step.

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"
      }
    }'

To confirm receipt of the webhook, your server must return:

• 200, 201, or 204 HTTP code in case of a successful response.
• 400 HTTP code with description of the problem if the specified user was not found or an invalid signature was passed. Your webhook handler may also return a 5xx HTTP code in case of temporary issues on your server.

If the Xsolla server did not receive a response to Successful payment for order and Order cancellation webhooks or received a response with a 5xx code, the webhooks are resent according to the following schedule:

• 2 attempts with a 5-minute interval
• 7 attempts with a 15-minute interval
• 10 attempts with a 60-minute interval

Maximum of 20 attempts to send webhooks are made within 12 hours from the first attempt.

If the Xsolla server did not receive a response to Payment webhook or the Refund webhook, or received a response with a 5xx code, webhooks are also resent with an increased time interval. A maximum of 12 attempts are made within 12 hours.

If the Xsolla server did not receive a response to the User validation webhook or received a response with a code of 400 or 5xx, the User validation webhook is not resent. In this case, the user sees an error and the Payment and Successful payment for order webhooks are not sent.

Error codes for HTTP code 400:

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