Fulfill order

Set up webhooks

If you use Xsolla player inventory, you can skip this step.
If you set up integration on the server side, you need to validate created orders by sending the respective code in response to webhooks. If you set up integration on the client side, webhooks will allow you receive notifications about configured events (e.g., change of payment status).
Use ready classes for processing webhooks.

To set up webhooks on Xsolla’s side:

  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 webhook URL.
  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.

To test webhooks, you can select any dedicated website, such as webhook.site.

We recommend that you implement the following webhooks:

User validationSent at different stages of the payment process to ensure the user is registered in the game.
PaymentSent when an order is paid and contains payment data and transaction details.
Successful payment of the orderSent when a Payment webhook has been successfully processed and contains information about purchased items and the transaction ID. Use the data from the webhook to add items to the user.
RefundSent when an order has been canceled and contains information about the details of the canceled payment and transaction details.
Partial refundSent when an order has been partially canceled and contains information about the details of the canceled payment and transaction details.

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.

The complete list and mechanism of webhooks, along with detailed examples of their processing, are described in the webhooks documentation.

Grant purchase to user

After a successful payment, implement granting the purchase to the user in the game on your side. To receive notifications about successful payments and order details, configure the following webhooks:

Your progress
Thank you for your feedback!
Last updated: November 6, 2023

Found a typo or other text error? Select the text and press Ctrl+Enter.

Report a problem
We always review our content. Your feedback helps us improve it.
Provide an email so we can follow up
Thank you for your feedback!