Set up webhooks

Webhooks are notifications about events occurring in the system. When a specific event occurs, Xsolla sends an HTTP request, in which event data is transmitted, to your application. This is usually a POST request in JSON format.

Event examples:

• user interaction with an item catalog
• payment or cancellation of an order

List of webhooks

For the full operation of the in-game store and payment management, it is necessary to implement the processing of the main webhooks:

The scheme below shows the process of purchasing and returning items using combined webhooks.

  sequenceDiagram
    participant User
    participant GameClient as Game Client
    participant Xsolla
    participant GameServer as Game Server
    %% Item Purchase
        Note over User, GameServer: Item purchase
        User ->> GameClient: Logs in
        GameClient ->> Xsolla: Sends user authentication request
        Xsolla -->> GameClient: Returns JWT / OAuth 2.0 token
        GameClient ->> Xsolla: Sends JWT, project ID, pagination parameters
        Xsolla -->> GameClient: Returns array of items
        GameClient -->> User: Displays storefront
        User ->> GameClient: Selects item and clicks Buy
        GameClient ->> Xsolla: Creates order request
        Xsolla -->> GameClient: Returns payment token
        GameClient ->> Xsolla: Opens payment UI URL with received token
        Xsolla ->> GameServer: Sends User validation webhook
        GameServer -->> Xsolla: Returns success status code
        Xsolla -->> User: Displays payment UI
        User ->> Xsolla: Chooses payment method and clicks Pay
        Xsolla ->> GameServer: Sends Successful payment for order webhook
        GameServer ->> GameServer: Grants purchases to user
        GameServer -->> Xsolla: Returns success status code
        Xsolla -->> User: Shows successful purchase screen
    %% Refund / Chargeback
        Note over User, GameServer: Refund / Chargeback
        User ->> Xsolla: Requests refund or chargeback
        Xsolla ->> GameServer: Sends Order cancellation webhook
        GameServer ->> GameServer: Removes items from user inventory
        GameServer -->> Xsolla: Returns success status code
        Xsolla -->> User: Refunds the payment

If item catalog personalization is implemented on your application’s side, set up processing of Catalog personalization on the partner’s side.

Set up webhooks in Publisher Account

To enable receiving webhooks:

1. In the project in Publisher Account go to Settings > Webhooks section.
2. In the Webhook server field, specify the URL of your server where you want to receive webhooks in the https://example.com format. You can also specify the URL you find in a tool for testing webhooks.

3. A secret key to sign project webhooks is generated by default. If you want to generate a new secret key, click the refresh icon.
4. Click Enable webhooks.

When you save the URL in the Webhook server field, you can see the Advanced settings section where you can give permissions to receive detailed information in webhooks. To do that, set the necessary toggles to active. In the line of each permission, you can see the list of webhooks affected by the settings.

1. In the project in Publisher Account go to the Settings > Webhooks section.
2. Click Disable webhooks.

Test webhooks in Publisher Account

A section to test webhooks is displayed in Publisher Account below the advanced settings once you enable webhooks in your project.

You can test the following webhooks:

1. In the webhooks testing section, go to the Payments and Store tab.
2. In the drop-down menu, select the item type. If the selected item type is not configured in your project, you will see a button to go to set up the items.
3. Fill in the necessary fields:
   • Xsolla order ID — order ID on Xsolla’s side. When testing, you can use any numeric value.
   • Xsolla invoice ID — transaction ID on Xsolla’s side. When testing, you can use any numeric value.
   • Items — items for which you want to receive information in the webhook. Select the items’ SKU from the drop-down list and indicate the amount. You can choose multiple items of the same type by clicking + and adding them in a new row.
   • User ID — when testing, you can use any combination of letters and digits.
   • Invoice ID — transaction ID on your game’s side. When testing, you can use any combination of letters and digits. It is not a required parameter for a successful payment but you can pass it to link the transaction ID on your side to the transaction ID on Xsolla side.
   • Amount — payment amount. When testing, you can use any numeric value.
   • Currency — select a currency from the drop-down list.
4. Click Test webhook.

Successful payment for order, Order cancellation, and User validation webhooks with the specified data are sent to the provided URL. The results of testing each webhook type are displayed below the Test webhook button. For each webhook, you need to configure processing both scenarios: a successful one and the one with an error.

Webhook listener

Webhook listener is program code that allows receiving incoming webhooks at a specified URL address, generating a signature, and sending a response to the Xsolla webhook server.

Generation of signature

When receiving a webhook, you should ensure the security of data transmission. To achieve this, a signature must be generated from the webhook data and verified that it matches the signature sent in the HTTP request header.

To generate a signature:

1. Concatenate the JSON from the request body and the project’s secret key.
2. Apply the SHA-1 cryptographic hash function to the string obtained in the first step.

Sending responses to webhook

To confirm receipt of the webhook, your server must return:

• 200, 201, or 204 HTTP code in case of a successful response.
• 400 HTTP-code with description of the problem if the specified user was not found or an invalid signature was passed.

Your webhook handler may also return a 5xx code in case of temporary issues on your server.

If the Xsolla server doesn’t receive a response to the Successful payment for order and Order cancellation webhooks or receives a response with a 5xx code, the webhooks are resent according to the following schedule:

• 2 attempts with a 5-minute interval
• 7 attempts with a 15-minute interval
• 10 attempts with a 60-minute interval

Maximum of 20 attempts to send webhooks are made within 12 hours from the first attempt.

The retry logic for the Payment and Refund webhooks is described on the respective webhook page.

If the Xsolla server doesn’t receive a response to the User validation webhook or receives a response with a code of 400 or 5xx, the User validation webhook is not resent.

In this case, an error is shown to the user and the Payment and Successful payment for order webhooks are not sent.

Configuring item information in webhooks

You can configure which item data is included in the Successful payment for order and Order cancellation webhooks via the items array.

Enabling additional parameter inclusion

Enable the inclusion of additional parameters that indicate:

• whether the item is free (is_free)
• whether the item is a bonus (is_bonus)
• whether the item is part of a bundle (is_bundle_content)

To receive these parameters, you must switch your webhooks to version 2 using the Update information about webhook settings API call. In version 1 (default), these parameters are not available.

Example of an items array with additional parameters:

 1"items": [
 2      {
 3        "sku": "com.xsolla.item_new_1",
 4        "type": "bundle",
 5        "is_pre_order": false,
 6        "is_free": false,
 7        "is_bonus": false,
 8        "is_bundle_content": false,
 9        "quantity": 1,
10        "amount": "1000",
11        "promotions": []
12      },
13      {
14        "sku": "com.xsolla.gold_1",
15        "type": "virtual_currency",
16        "is_pre_order": false,
17        "is_free": false,
18        "is_bonus": false,
19        "is_bundle_content": true,
20        "quantity": 1500,
21        "amount": "[null]",
22        "promotions": []
23      }
24 ]

Disabling bundle content inclusion

By default, webhooks include all items from the bundle as a list of individual items. You can configure the webhook to include only the bundle itself, without listing its contents.

In this case, the items included in the bundle are not included in the items array. In the array shown above, the item with the SKU com.xsolla.gold_1, which is part of the bundle, is excluded.

Example of the items array when bundle content is disabled:

 1
 2"items": [
 3      {
 4        "sku": "com.xsolla.item_new_1",
 5        "type": "bundle",
 6        "is_pre_order": false,
 7        "is_free": false,
 8        "is_bonus": false,
 9        "is_bundle_content": false,
10        "quantity": 1,
11        "amount": "1000",
12        "promotions": []
13      }
14 ]

To disable bundle content inclusion, contact your Customer Success Manager or email to csm@xsolla.com.