Overview

Webhooks allow you to receive notifications of events that happen to your Xsolla transactions. Use webhooks to automate back-end and supplementary functions, such as providing status and other transaction-related information.

We use webhooks for payments, including purchases of virtual currency, items, games, physical goods and so on.

In most cases, webhooks are triggered by user actions on your website. But they can come from other actions, too. For example, a back-end process on your website may invoke an API method to refund a payment, or the payment system may send a notification about a disputed charge.

You must write or use a so-called listener, or handler, to receive and process webhooks. This is a program that waits for a webhook and usually passes it to an internal workflow of yours, which responds appropriately.

For example, you can do the following after receiving a webhook:

  • Filling up a user’s balance
  • Unlocking new item for a user
  • Delivering physical goods to a user

Listen to webhooks at the following IP addresses: 185.30.20.0/24, 185.30.21.0/24, 185.30.23.0/24.

Notice: Your database must NOT contain two successful transactions with the same ID. If your listener receives a webhook with an existing transaction ID, it must return the latest result for that transaction. Avoid charging the user twice or creating duplicate records in your database.

We cannot guarantee that your listener will receive all the webhooks we send. As internet connection is not 100% reliable, webhooks may fail to come on time or at all. Moreover, your listener may return a 5xx HTTP code for a temporary error on your server. For example, your listener returns a 500 HTTP response code in case a virtual item that a user purchased successfully was not added to the user’s inventory.

To reduce the risk of lost messages, the Xsolla alert service uses a retry mechanism. For messages that don’t reach their destination, the service resends them per the following frequency:

  • 2 times with an interval of 5 minutes
  • 7 times with an interval of 15 minutes
  • 10 times with an interval of 60 minutes
A repeated webhook may be sent within 12 hours after the previous one. The maximum number of retries is 20.

Note: Although connection problems may indeed result in lost, delayed, or duplicate webhooks, the most common cause is faulty logic on the listener side.
Was this article helpful?
Thank you!
Is there anything we can improve? Message
We’re sorry to hear that
Please explain why this article wasn’t helpful to you. Message
Thank you for your feedback!
We’ll review your message and use it to help us improve your experience.
Rate this page
Rate this page
Is there anything we can improve?

Don’t want to answer

Thank you for your feedback!
Last updated: August 4, 2021

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!