Основные положения

Вебхуки — это оповещения о происходящих в системе событиях. При наступлении определенного события Xsolla отправляет HTTP-запрос к вашему приложению, в котором передаются данные о событии. Чаще всего отправляется POST-запрос в JSON-формате.

Примеры событий:

• взаимодействие пользователя с каталогом товаров;
• оплата или отмена заказа.

Когда происходит настроенное событие, Xsolla через вебхук оповещает вашу систему об этом. В результате вы можете:

• пополнить баланс пользователя;
• выполнить возврат платежа;
• начислить новые предметы пользователю или списать их;
• начать предоставление подписки;
• заблокировать пользователя в случае подозрения в мошенничестве.

Пример работы вебхука обработки платежей:

Видеоинструкция по интеграции вебхуков Xsolla:

Настройка вебхуков при работе с продуктами и решениями Xsolla:

Список обязательных вебхуков

Если вы используете продукты и решения, для которых работа с вебхуками обязательна, подключите и протестируйте вебхуки в Личном кабинете и настройте их обработку. При наступлении определенных событий вебхуки отправляются последовательно. Поэтому, если вы не обработаете какой-то из вебхуков, последующие вебхуки не будут отправлены. Список необходимых вебхуков представлен ниже.

Store и Payments

На стороне Xsolla настроено 2 варианта отправки вебхуков при покупке и возврате товаров на сайте — информация с данными платежа и транзакции и информация о купленных товарах может приходить отдельно или может быть объединена в один вебхук.

Получение информации в объединенных вебхуках:

Если вы зарегистрировались в Личном кабинете после 22 января 2025 г., вы получаете всю информацию в вебхуках Успешная оплата заказа (order_paid) и Отмена заказа (order_canceled). В этом случае вам не требуется обрабатывать вебхуки Успешный платеж (payment) и Возврат платежа (refund).

Получение информации в отдельных вебхуках:

Если вы зарегистрировались в Личном кабинете до 22 января 2025 г. включительно, вы получаете вебхуки:

• Успешный платеж (payment) и Возврат платежа (refund) с информацией о данных платежа и детали транзакции.
• Успешная оплата заказа (order_paid) и Отмена заказа (order_canceled) с информацией о купленных товарах.

Вам необходимо обрабатывать все поступающие вебхуки. Для перехода к новому варианту с получением объединенных вебхуков обратитесь к персональному менеджеру проекта или напишите на csm@xsolla.com.

Для полноценной работы внутриигрового магазина и управления платежами, необходимо реализовать обработку основных вебхуков:

Если вы получаете объединенные вебхуки:

Если вы получаете отдельные вебхуки:

Если вы используете персонализацию каталога товаров, реализованную на стороне вашего приложения, настройте обработку вебхука Персонализация каталога на стороне партнера.

Subscriptions

Для автоматического управления планами подписок необходимо реализовать обработку основных вебхуков:

• Проверка существования пользователя (user_validation) — отправляется на разных этапах оплаты, чтобы удостовериться, что пользователь зарегистрирован в игре.
• Успешный платеж (payment) — отправляется, когда заказ оплачен, и содержит информацию о данных платежа и детали транзакции.
• Создание подписки (create_subscription) — отправляется, когда был получен ответ об успешной обработке вебхука Успешный платеж или пользователь приобрел подписку с пробным периодом. Содержит детали купленной подписки и данные пользователя. Используйте данные вебхука для добавления подписки пользователю.
• Изменение подписки (update_subscription) — отправляется при продлении или изменении подписки, когда был получен ответ об успешной обработке вебхука Успешный платеж. Содержит детали купленной подписки и данные пользователя. Используйте данные вебхука для продления подписки пользователю или изменения параметров подписки.
• Возврат платежа (refund) — отправляется, когда заказ был отменен, и содержит информацию о данных отмененного платежа и детали транзакции.
• Отмена подписки (cancel_subscription) — отправляется, если был получен ответ об успешной обработке вебхука Возврат платежа или подписка была отменена по другой причине. Содержит информацию о подписке и данные пользователя. Используйте данные вебхука для списания купленных подписок у пользователя.

Настройка вебхуков в Личном кабинете

Общие настройки

Чтобы включить получение вебхуков:

1. В проекте в Личном кабинете перейдите в раздел Настройки проекта > Вебхуки.
2. В поле Сервер для вебхуков укажите URL-адрес вашего сервера для получения вебхуков в формате https://example.com. Вы также можете ввести URL-адрес из инструмента для тестирования вебхуков.

3. Создайте секретный ключ:

1. В разделе Secret keys нажмите Add key.
2. В открывшемся модальном окне введите название ключа, которое позволит идентифицировать его в общем списке.
3. Нажмите Create key.
4. Нажмите Copy secret и сохраните созданный ключ на вашей стороне.
5. Нажмите Done.
6. Подтвердите, что вы сохранили ключ, и нажмите Ok, close.

4. Нажмите Получать вебхуки.

Чтобы отключить получение вебхуков:

1. В проекте в Личном кабинете перейдите в раздел Настройки проекта > Вебхуки.
2. Нажмите Отключить вебхуки.

Ротация секретных ключей

Регулярное обновление секретных ключей повышает безопасность вашей интеграции. В одном проекте вы можете создать до 5 секретных ключей, чтобы обеспечить их ротацию. Для этого:

1. В разделе Настройки проекта > Вебхуки нажмите Add key.

2. В открывшемся модальном окне введите название ключа, которое позволит идентифицировать его в общем списке.
3. Нажмите Create key.
4. Нажмите Copy secret и сохраните созданный ключ на вашей стороне.
5. Нажмите Done.
6. Подтвердите, что вы сохранили ключ, и нажмите Ok, close.

В проекте может быть только один активный секретный ключ. Если вы хотите его изменить, нажмите Set as active у другого ключа и подтвердите действие. После успешной миграции на новый ключ мы рекомендуем удалять деактивированные ключи.

Расширенные настройки

Для вебхуков раздела Payments and Store доступны расширенные настройки. Они автоматически отобразятся под блоком Общие настройки после того, как вы нажмете кнопку Получать вебхуки.

В этом разделе вы можете настроить получение дополнительной информации в вебхуках. Для этого установите соответствующие переключатели в активное положение. В строке каждого разрешения указаны вебхуки, на которые повлияют изменение настроек.

Тестирование вебхуков в Личном кабинете

Тестирование вебхуков помогает убедиться в корректной настройке проекта как на вашей стороне, так и на стороне Xsolla.

Если вебхуки настроены успешно, ниже блока настройки вебхуков отобразится блок тестирования вебхуков.

Содержание блока зависит от варианта получения вебхуков.

Если вы зарегистрировались в Личном кабинете после 22 января 2025 г., вы получаете объединенные вебхуки:

Если вы зарегистрировались в Личном кабинете до 22 января 2025 г., вы получаете отдельные вебхуки:

Далее описан процесс тестирования для сценария с объединенными вебхуками.

Payments and Store

На вкладке Payments and Store вы можете протестировать работу следующих вебхуков:

• Проверка пользователей (user_validation)
• Успешная оплата заказа (order_paid)
• Отмена заказа (order_canceled)

Чтобы протестировать вебхуки:

1. В блоке тестирования вебхуков перейдите на вкладку Payments and Store.
2. В раскрывающемся списке выберите тип товара. Если выбранный тип товара еще не настроен в Личном кабинете, нажмите кнопку для перехода к настройке товара соответствующего типа. После создания товара вернитесь в раздел тестирования вебхуков и перейдите к следующему шагу.
3. Заполните необходимые поля:
   • ID пользователя — при тестировании вы можете указать любую комбинацию букв и цифр.
   • Укажите произвольное значение в поле ID заказа Xsolla.
   • ID заявки в Xsolla — ID транзакции на стороне Xsolla. При тестировании вы можете указать любое числовое значение.
   • Invoice ID — ID транзакции на стороне вашей игры. При тестировании вы можете указать любую комбинацию букв и цифр. Для успешной оплаты это не обязательный параметр, но вы можете передать его, чтобы связать ID транзакции на вашей стороне с ID транзакции на стороне Xsolla.
   • Сумма — сумма платежа. При тестировании вы можете указать любое числовое значение.
   • Валюта — выберите валюту из раскрывающегося списка.
   • Выберите артикул товара из раскрывающегося списка и укажите его количество. Вы можете выбрать несколько товаров. Для этого нажмите + и добавьте товары в новой строке.
4. Нажмите Проверить вебхуки.

На URL-адрес сервера вебхуков придут вебхуки Проверка существования пользователя, Успешная оплата заказа и Отмена заказа с указанными данными. Ниже кнопки Проверить вебхук отобразятся результаты тестирования каждого типа вебхука.

Если в вашем проекте в разделе Настройки проекта > Настройки интеграции установлен флажок Использовать public user ID, на URL-адрес сервера вебхуков также придет вебхук Поиск пользователя и в разделе тестирования отобразится результат его проверки.

Для каждого вебхука вам необходимо настроить обработку обоих сценариев: успешного и с ошибкой.

Subscriptions

На вкладке Subscriptions вы можете протестировать работу следующих вебхуков при управлении подписками:

• Проверка пользователей (user_validation)
• Успешный платеж (payment)

Чтобы протестировать вебхуки:

1. В блоке тестирования вебхуков перейдите на вкладку Subscriptions.
2. Заполните необходимые поля:
   • ID пользователя — при тестировании вы можете указать любую комбинацию букв и цифр.
   • ID заявки в Xsolla — ID транзакции на стороне Xsolla. При тестировании вы можете указать любое числовое значение.
   • Public user ID — ID, который известен пользователю, например, email или никнейм. Это поле отображается, если в вашем проекте в разделе Настройки проекта > Настройки интеграции установлен флажок Использовать public user ID.
   • Сумма — сумма платежа. При тестировании вы можете указать любое числовое значение.
   • Валюта — выберите валюту из раскрывающегося списка.
   • ID плана — план подписки. Выберите план из раскрывающегося списка.
   • Продукт подписки — выберите продукт из раскрывающегося списка (опционально). Список отображается, если в вашем проекте есть настроенные продукты.
   • Invoice ID — ID транзакции на стороне вашей игры. При тестировании вы можете указать любую комбинацию букв и цифр. Для успешной оплаты это не обязательный параметр, но вы можете передать его, чтобы связать ID транзакции на вашей стороне с ID транзакции на стороне Xsolla.
   • Пробный период. Для тестирования покупки подписки без пробного периода или тестирования продления подписки , укажите значение 0.
3. Нажмите Протестировать.

На указанный URL-адрес придут вебхуки с введенными данными. Ниже кнопки Протестировать отобразятся результаты тестирования каждого вебхука как для успешного сценария, так и для случая возникновения ошибки.

Обработчик вебхуков

Обработчик вебхуков – это программный код, который позволяет принимать поступающие вебхуки на указанный URL-адрес, генерировать подпись и отправлять ответ на вебхук на сервер Xsolla.

На стороне вашего приложения реализуйте прием вебхуков со следующих IP-адресов:

• 185.30.20.0/24;
• 185.30.21.0/24;
• 185.30.22.0/24;
• 185.30.23.0/24;
• 34.102.38.178;
• 34.94.43.207
• 35.236.73.234;
• 34.94.69.44;
• 34.102.22.197.

Если у вас подключен продукт Login, дополнительно добавьте обработку вебхуков со следующих IP-адресов:

• 34.94.0.85;
• 34.94.14.95;
• 34.94.25.33;
• 34.94.115.185;
• 34.94.154.26;
• 34.94.173.132;
• 34.102.48.30;
• 35.235.99.248;
• 35.236.32.131;
• 35.236.35.100;
• 35.236.117.164.

Ограничения:

• В базе данных вашего приложения не должно быть нескольких успешных транзакций с одинаковым ID.
• Если обработчик вебхуков получил вебхук с ID, который уже существует в базе, необходимо вернуть результат предыдущей обработки данной транзакции. Не рекомендуется зачислять пользователю повторную покупку и создавать дублирующие записи в базе данных.

Генерация подписи

Чтобы обеспечить безопасную передачу данных, вам необходимо убедиться, что вебхук действительно был отправлен с сервера Xsolla и не был изменен в процессе передачи. Для этого сгенерируйте собственную подпись на основе тела запроса и сравните ее с подписью, полученной в заголовке authorization этого же запроса. Если подписи совпадают, вебхук является подлинным и его можно обрабатывать.

Шаги верификации:

1. Получите подпись из заголовка authorization входящего запроса вебхука. Формат заголовка: Signature <signature_value>.

2. Получите тело запроса вебхука в формате JSON.

   Внимание

   Используйте JSON в полученном виде. Не парсите и не перекодируйте данные, так как это изменит форматирование и приведет к ошибке проверки подписи.

3. Сгенерируйте собственную подпись для сравнения:

   1. Конкатенируйте JSON из тела запроса и секретный ключ проекта, т. е. объедините две строки, добавив секретный ключ проекта в конец строки.
   2. Примените к полученной строке криптографическую хэш-функцию SHA-1. В результате вы получите шестнадцатеричную строку в нижнем регистре.

4. Сравните полученную строку с подписью из заголовка authorization. Если подписи совпадают, вебхук является подлинным.

Ниже вы можете найти примеры реализации генерации подписи для следующих языков: C#, C++, Go, PHP и Node.js.

Пример вебхука (HTTP):

Пример вебхука (curl):

Пример реализации генерации подписи для C# (универсальный пример):

Пример реализации генерации подписи для C# (.NET 5.0 и выше):

Пример реализации генерации подписи для C# (.NET 7.0 и выше):

Пример реализации генерации подписи для C++:

Пример реализации генерации подписи для Go:

Пример реализации генерации подписи для PHP:

Пример реализации генерации подписи для Node.js:

Отправка ответов на вебхук

Чтобы подтвердить получение вебхука, ваш сервер должен вернуть:

• 200, 201, или 204 HTTP-код в случае успешного ответа.
• 400 HTTP-код с описанием проблемы, если указанный пользователь не был найден или если передана недействительная подпись. Ваш обработчик вебхуков также может возвращать 5xx HTTP-код при временных проблемах на вашем сервере.

Если на вебхуки Успешная оплата заказа и Отмена заказа сервер Xsolla не получил ответ или получил ответ с кодом 5xx, осуществляется повторная отправка вебхуков по следующему расписанию:

• 2 попытки с интервалом 5 минут;
• 7 попыток с интервалом 15 минут;
• 10 попыток с интервалом 60 минут.

Максимально осуществляется 20 попыток отправки вебхуков в течение 12 часов с момента первой попытки.

Логика повторной отправки вебхуков Успешный платеж и Возврат платежа описана на странице соответствующего вебхука.

Если на вебхук Проверка существования пользователя сервер Xsolla не получил ответ или получил ответ с 400 или 5xx HTTP-кодом, повторная отправка вебхука Проверка существования пользователя не осуществляется. Пользователь увидит ошибку, вебхуки Успешный платеж и Успешная оплата заказа отправлены не будут.

Ошибки

Коды ошибок для HTTP-кода 400:

Лучшие практики

Безопасность

Соблюдайте следующие рекомендации:

• Используйте только протокол HTTPS с действительным сертификатом.
• При проверке подписи всегда используйте тело запроса в полученном виде — не парсите и не перекодируйте данные.
• Не передавайте чувствительные данные в URL-адресах и не раскрывайте технические детали в сообщениях об ошибках.
• Отключите проверку CSRF для URL-адреса вебхука — входящие запросы от Xsolla не содержат токен CSRF и будут отклонены без этой настройки.
• Добавьте IP-адреса Xsolla в белый список.

Архитектура обработчика вебхуков

Соблюдайте следующие рекомендации:

1. Принимайте POST-запрос с телом запроса и заголовками, не изменяя их.
2. Сгенерируйте подпись для проверки подлинности вебхука и верните в ответе соответствующий статус:
   • 4xx — при несовпадении подписей.
   • 2xx — в случае успешного ответа. Мы рекомендуем вернуть 204 No Content до выполнения основной бизнес-логики. 200 OK также допустим.
3. Передайте тело ответа (payload) в асинхронную задачу или очередь для дальнейшей обработки.
4. Обеспечьте идемпотентность. Ваша система должна быть готова к повторному получению вебхуков.

Пример сценария:

Идемпотентность и дубликаты

Соблюдайте следующие рекомендации:

• Используйте ID транзакции и/или внешний ID, ID заказа в качестве ключей идемпотентности.
• Сохраняйте обработанные ID и возвращайте прежний результат при получении дубликата.
• Исключите повторное начисление товаров, двойное списание средств и дублирование записей в базе данных.
• Обратите внимание, что при последовательной доставке сбой на более раннем событии блокирует обработку последующих.

Стабильность системы

Соблюдайте следующие рекомендации:

• Для выполнения ресурсозатратных задач (таких как обращение к внешним сервисам, биллинг или начисление товаров) используйте очереди и асинхронный подход.
• Установите интервалы для обработчика вебхука (1–3 с). При временных сбоях полагайтесь на механизм повторной отправки Xsolla.
• Не используйте обработчик для повторной отправки вебхуков — это выполняется на стороне Xsolla.
• Логируйте время отправки вебхуков и статусы их обработки, настройте оповещения при резком росте ошибок 5xx и повторных попыток.
• Передавайте ID корреляции из вебхука в логи и систему мониторинга (APM).
• Настройте логирование и мониторинг ошибок. В случае неустранимых ошибок перемещайте задачи в очередь недоставленных сообщений (dead-letter queue, DLQ). Реализуйте инструмент безопасного воспроизведения событий, защищенный механизмом идемпотентности.

Примеры реализации

Успешная покупка — начисление выполнено один раз:

Повторная отправка (таймаут на стороне партнера):

Возврат платежа:

Недоступность сервера партнера:

Частые вопросы

Необходимо ли для вебхуков использовать HTTPS?

Да.

Могу ли я получать платежные вебхуки на несколько URL-адресов?

Нет. Платежные вебхуки работают по протоколу Server-to-Server и отправляются на один URL-адрес, указанный в настройках проекта. Если вы хотите получать оповещения в вашей игре, на сайте или мобильном приложении, реализуйте отправку вебхуков на собственном сервере, чтобы пересылать данные между Xsolla и игрой. Вы также можете протестировать работу вебхуков из консоли разработчика.

Почему оповещение от Xsolla не пришло на URL-адрес вебхука?

Убедитесь, что ваш вебхук-сервер поддерживает POST и GET HTTP-запросы.

Как предотвратить дубликаты ID транзакций при обработке?

Используйте внешний ID — это ID транзакции в игре, который присваивается заказу в вашей системе. На стороне Xsolla внешний ID связан с ID транзакции, поэтому наличие внешнего ID позволяет Xsolla предотвращать повторную оплату одной и той же транзакции. Подробная информация о настройке приведена в документации.

Какие есть лучшие практики работы с вебхуками?

Мы рекомендуем:

• Возвращать код 204 или 200 сразу после проверки подписи.
• Проверять подпись вебхука, не изменяя тело запроса.
• Обеспечить идемпотентность всех операций.
• Логировать все операции и настроить мониторинг ошибок.
• Не передавать чувствительные данные в URL-адресах и не раскрывать технические детали в сообщениях об ошибках.

Подробная информация приведена в разделе с лучшими практиками.

Краткий чеклист интеграции вебхуков

Для корректной работы вебхуков убедитесь, что перед запуском проекта выполнены следующие пункты:

• Используется протокол HTTPS.
• Реализована проверка подписи вебхука без изменения тела запроса.
• Ответ 204/200 отправляется, как только подтверждена подпись.
• Обеспечена идемпотентность всех операций.
• Настроены логирование ошибок и их мониторинг.
• Чувствительные данные не передаются в URL-адресах, и технические детали не раскрываются в сообщениях об ошибках.
• Поддерживаются повторные попытки отправки вебхуков с учетом логики работы Xsolla.
• Вся интеграция задокументирована.

Список вебхуков