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:
When a configured event occurs, Xsolla notifies your system about it via webhooks. For example, you can do the following after receiving a webhook:
Below is an example of how a payment processing webhook works:
The following settings have to be applied for webhooks to work correctly:
185.30.20.0/24
, 185.30.21.0/24
, 185.30.23.0/24
.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.
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.
Digital signatures enable secure data transmission. To generate a signature:
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"
}
}
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 . |
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. |