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:

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.

• 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.

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.

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

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