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:,,,,
  • Application database must not contain two successful transactions with the same ID.


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.


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

Resend webhooks

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.

If a response with a 4xx code was received, Xsolla doesn’t resend webhooks.

If a response with a 5xx code is received for the Refund and Payment webhooks, Xsolla resends a webhook with an increased time interval until your listener confirms receiving. The maximum number of retries is 12.


If Xsolla initiates a refund and a response with a 5xx code is received for the Refund webhook, the payment will still be refunded.


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
      "name":"Xsolla User",
curl -v 'https://your.hostname/your/uri' \
-H 'Authorization: Signature 52eac2713985e212351610d008e7e14fae46f902' \
-d '{
        "ip": "",
        "phone": "18777976552",
        "email": "email@example.com",
        "id": 1234567,
        "name": "Xsolla User",
        "country": "US"


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
        "message":"Invalid user"

Webhooks list


The notification type is sent in the notification_type parameter.

Webhook Notification type Description
User validation user_validation Sent to check if a user exists in the game.
User search user_search Sent to get user info based on public user ID.
Payment payment Sent when a user completes a payment.
Refund refund Sent when a payment must be canceled for any reason.
Partial refund partial_refund Sent when a payment must be partially canceled for any reason.
AFS rejected transaction afs_reject Sent when a transaction is declined during an AFS check.
AFS updated blocklist afs_black_list Sent when the AFS blocklist is updated.
Created subscription create_subscription Sent when a user creates a subscription.
Updated subscription update_subscription Sent when a subscription is renewed or changed.
Canceled subscription cancel_subscription Sent when a subscription is canceled.
Nonrenewing subscription non_renewal_subscription Sent when status is set to nonrenewing.
Add payment account payment_account_add Sent when a user adds or saves a payment account.
Remove payment account payment_account_remove Sent when a user removes the payment account from saved accounts.
User validation in Web Shop - Sent from a Web Shop site to check if a user exists in the game.
Catalog personalization on partner’s side partner_side_catalog Sent when a user interacts with the store.
Successful payment of the order order_paid Sent when an order is paid.
Order cancellation order_canceled Sent when an order is canceled.