Webhooks

Webhooks are notifications about events occurring within the Xsolla eco-system. When a specific event occurs, Xsolla makes a web-request to the configured endpoint, transmitting event data to your game server. These webhooks are essential, when performing user validation and handling the payment flow outcomes on the game's backend.

Setting up Webhooks in Publisher Account

Enabling Webhooks

• Open your project in the Publisher Account.
• Click Project settings in the side menu and navigate to the Webhooks tab (1).
• Select Use webhooks (2).
• In the Webhook server field (3), specify the URL of your server where you want the webhooks to be sent to (e.g. https://www.my-backend.com/webhooks).
• A secret key (4) to sign project webhooks is generated by default. If you want to generate a new secret key, click the refresh icon.
• Click on Enable webhooks.

Disabling Webhooks

• Open your project in the Publisher Account.
• Click Project settings in the side menu and navigate to the Webhooks tab (1).
• Click on Disable webhooks (2).

Enabling Xsolla Events API

The Xsolla Events API (Events API) serves as an alternative to the conventional webhook-based integrations, where the integrator’s backend usually handles most of the logic (purchase validation, awarding, etc.). Instead of sending webhooks directly, the API intercepts them and stores their payloads in a remote queue managed by Xsolla. This approach enables serverless integrations for projects that lack backend capacity or don't require one, yet still prefer handling the entire transaction flow directly from the app. The SDK leverages the Events API to support this type of integration.

CAUTION

Opting for the Xsolla Events API disables your project's webhooks. In other words, you cannot simultaneously handle webhooks on your backend and use the Events API in your app.

To enable the Events API for your project, follow these simple steps:

• Open your project in the Publisher Account.
• Click Project settings in the side menu and navigate to the Webhooks tab (1).
• Select Use API (2).

提示

To turn the Xsolla Events API off, follow the steps above, but select Use Webhooks this time.

To initialize the SDK in Events API mode, see one of the following platform-specific guides below:

• Android
• iOS
• Unity

Working with Webhooks

Below are the examples of commonly used webhooks.

提示

For a complete list of supported webhooks visit here ↗.

User Validation (user_validation)

Example

curl -v 'https://your.hostname/your/uri' \
    -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
    -d '{
        "notification_type":"user_validation",
        "settings": {
            "project_id": 18404,
            "merchant_id": 2340
        },
        "user": {
            "ip": "127.0.0.1",
            "phone": "18777976552",
            "email": "email@example.com",
            "id": "1234567",
            "name": "John Smith",
            "country": "US"
        }
    }'

Payment (payment)

Example

curl -v 'https://your.hostname/your/uri' \
    -X POST \
    -d '{
            "notification_type": "payment",
            "settings": {
            "project_id": 18404,
            "merchant_id": 2340
        },
        "purchase": {
            "subscription": {
                "plan_id": "b5dac9c8",
                "subscription_id": "10",
                "product_id": "Demo Product",
                "date_create": "2014-09-22T19:25:25+04:00",
                "date_next_charge": "2014-10-22T19:25:25+04:00",
                "currency": "USD",
                "amount": 9.99
            },
            "checkout": {
                "currency": "USD",
                "amount": 50
            },
            "total": {
                "currency": "USD",
                "amount": 200
            },
            "promotions": [{
                "technical_name": "Demo Promotion",
                "id": 853
            }],
            "coupon": {
                "coupon_code": "ICvj45S4FUOyy",
                "campaign_code": "1507"
            },
            "order": {
                "id": 1234
                "lineitems": [
                    {
                        "sku": "test_1",
                        "quantity": 1,
                        "price": {
                            "currency": "EUR",
                            "amount": 6.5
                        }
                    }
                ]
            }
        },
        "user": {
            "ip": "127.0.0.1",
            "phone": "18777976552",
            "email": "email@example.com",
            "id": "1234567",
            "name": "John Smith",
            "country": "US"
        },
        "transaction": {
            "id": 1,
            "external_id": 1,
            "payment_date": "2014-09-24T20:38:16+04:00",
            "payment_method": 1,
            "payment_method_name": "PayPal",
            "payment_method_order_id": 1234567890123456789,
            "dry_run": 1,
            "agreement": 1
        },
        "payment_details": {
            "payment": {
                "currency": "USD",
                "amount": 230
            },
            "vat": {
                "currency": "USD",
                "amount": 0,
                "percent": 20
            },
            "sales_tax": {
                "currency": "USD",
                "amount": 0,
                "percent": 0
            },
            "direct_wht": {
                "currency": "USD",
                "amount": 0,
                "percent": 0
            },
            "payout_currency_rate": "1",
            "payout": {
                "currency": "USD",
                "amount": 200
            },
            "xsolla_fee": {
                "currency": "USD",
                "amount": 10
            },
            "payment_method_fee": {
                "currency": "USD",
                "amount": 20
            },
            "repatriation_commission": {
                "currency": "USD",
                "amount": 10
            }
        },
        "custom_parameters": {
            "parameter1": "value1",
            "parameter2": "value2"
        }
    }'