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

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.
Activate key	Buy Button	redeem_key	Sent when a user activates a key.
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 processing	Payouts	-	Sent to notify that payout transaction was created and is being processed.
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.
Successful payment of the order	In-Game Store	order_paid	Sent when an order is paid.
Order cancellation	In-Game Store	order_canceled	Sent when an order is canceled.