Set up order status tracking

To grant items to the user, you need to make sure that the payment was successful.

To track the status of created orders and validate them, you will need to configure webhooks processing on the server side of your application.

To switch to the new option with receiving combined webhooks, contact your Customer Success Managers or email to csm@xsolla.com.

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

• If you receive combined webhooks
• If you receive separate webhooks

Webhook name	Description
User validation > User validation (user_validation)	Is sent at different stages of the payment process to ensure the user is registered in the game.
Game services > Combined webhooks > Successful payment for order (order_paid)	It contains payment data, transaction details, and information about purchased items. Use the data from the webhook to add items to the user.
Game services > Combined webhooks > Order cancellation (order_canceled)	It contains data of the canceled payment, transaction details, and information about purchased items. Use the data from the webhook to remove the purchased items.

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

Webhook name	Description
User validation > User validation (user_validation)	Is sent at different stages of the payment process to ensure the user is registered in the game.
Payments > Payment (payment)	It contains payment data and transaction details.
Game services > Separate webhooks > Successful payment for order (order_paid)	It contains information about purchased items and the transaction details. Use the data from the webhook to add items to the user.
Payments > Refund (refund)	It contains payment data and transaction details.
Game services > Separate webhooks > Order cancellation (order_canceled)	It contains information about the purchased items and the ID of the canceled transaction. Use the data from the webhook to remove the purchased items.

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

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

For the full list of webhooks and general information about working with them, refer to the webhooks documentation.

PHP SDK

Use ready classes for processing webhooks.

Set up webhooks sending

To configure webhooks on the Xsolla side:

1. Open your project in Publisher Account.
2. Click Project settings in the side menu and go to the Webhooks section.
3. In the Webhook URL field, specify the URL to which Xsolla will send webhooks.

4. Click Enable webhooks.

Add 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.

If the Xsolla server doesn’t receive a response to Payment webhook or Refund webhook, or receives a response with a 5xx code, webhooks are also resent with an increased time interval. A maximum of 12 attempts are made within 12 hours.

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.