Set up webhooks

A webhook is program code that consists of parameters and their corresponding values. When a specific event occurs, an HTTP request with the updated parameter values is sent to your application. This is usually a POST request in JSON format.

Examples of events: user interaction with an item catalog, payment, or cancellation of an order.

List of webhooks

If you want to receive event notifications, implement webhook handling:

• Payment — is sent when an order is paid and contains payment data and transaction details.
• Successful payment of the order — is sent when a Payment webhook has been successfully processed and contains information about purchased items and the transaction ID.
• Refund — is sent when an order is canceled and contains the canceled payment data and transaction details.
• Order cancellation — is sent when a Refund webhook has been successfully processed and contains information about the purchased items and the ID of the canceled transaction.
• User validation — is sent at different stages of the payment process to ensure the user is registered in the game. Contains information about the user who buys the game key.

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

If you are using an external ID (transaction ID on your system) and want to associate it with a transaction ID on Xsolla’s side or pass additional parameters when validating the user, implement the webhook Transaction’s ID linking.

Setting up webhooks in Publisher Account

To set up webhooks:

1. Open your project in Publisher Account.
2. Click Project settings in the side menu and go to Webhooks.
3. Set the Webhooks toggle to On.
4. Specify the URL where you want to receive webhooks in the https://example.com format.
5. A secret key to sign project webhooks is generated by default. If you want to generate a new secret key, click the refresh icon.
6. Click Save settings.

Testing webhooks in Publisher Account

If you are using an external ID (transaction ID on your system) and want to associate it with a transaction ID on Xsolla’s side or pass additional parameters when validating the user, implement the webhook Transaction’s ID linking.

If webhooks are set up successfully, a webhook testing block is displayed below the webhook setup block.

• Successful payment of the order and Order cancellation
• Payment and User validation

Note

For testing, you must create at least one game key package.

To test the Successful payment of the order and Order cancellation webhooks:

1. In the webhook testing block, navigate to the Store tab.
2. In the drop-down menu, select Game keys. If the game key packages are not set up in Publisher Account, one the following buttons are displayed:
   • Connect – if the Game keys module is not connected
   • Configure – if you connected the module previously, but have not completed the setup

3. Enter any value in the Xsolla Order ID field.
4. Select the game keys package from the drop-down list.
5. Specify game publishing platforms.
6. Specify an arbitrary value of the game key in the Amount field.
7. Choose the currency in which the order will be paid.
8. Click Test.

Successful payment of the order and Order cancellation webhooks with the specified data are sent to the provided URL. The results of testing each webhook type are displayed below the Test buttons.

Note

If an error message appears in the testing block stating that the test has not passed, check the webhook response settings in your webhook listener. Information about these errors are available in the test results.

To test the Payment and User validation webhooks:

1. In the webhook testing block, navigate to the Payments tab.
2. Fill in the required fields:
   • User ID
   • Xsolla Invoice ID — transaction ID on Xsolla’s side
   • Amount
   • Currency — select a currency from the drop-down list
   • Invoice ID — transaction ID on your game’s side

1. You can use arbitrary values for testing.

1. The value in the User ID field is used to check if a user exists in the game. If you want to receive a successful response during testing, enter a value in the User ID field that can be successfully validated by your server.

3. Click Test.

Payment 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 buttons.

Note

If an error message appears in the testing block stating that the test has not passed, check the webhook response settings in your webhook listener. Information about these errors are available in the test results.

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:

• 204 HTTP-code with no message body 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 a response was not received for the Successful payment of the order and Order cancellation webhooks or if a response with a 5xx code was received, 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.

If for the Payment webhook a response was not received or if a response with a 5xx code was received, webhooks are also resent with an increased time interval. A maximum of 12 attempts are made within 12 hours.

If a response was not received for the User validation webhook or a response with a code of 400 or 5xx was received, the User validation webhook is not resent.

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

Rate this page

Is there anything we can improve? Send

Don’t want to answer

Thank you for your feedback!