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

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

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

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

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

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

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

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

Продукт/ Решение	Обязательно/ Опционально	Для чего нужны вебхуки
Payments	Обязательно	Валидация пользователей. Получение информации о деталях транзакции в случаях успешного платежа или возврата платежа. Начисление купленных товаров пользователю и списание товаров в случае отмены заказа.
In-Game Store	Обязательно	Валидация пользователей. Получение информации о деталях транзакции в случаях успешного платежа или возврата платежа. Начисление купленных товаров пользователю и списание товаров в случае отмены заказа.
Game Sales	Опционально	Для продажи ключей не требуется валидация пользователя и начисление ему товаров. Вы можете подключить вебхуки, если вы хотите получать информацию о событиях, например об оплате или отмене заказа. Если вы подключите вебхуки, важно обрабатывать все поступающие обязательные вебхуки.
Subscriptions	Опционально	Получение информации о создании, изменении или отмене подписки. Альтернативный вариант — запрос информации с помощью API.
Web Shop	Обязательно	Валидация пользователей. Получение информации о деталях транзакции в случаях успешного платежа или возврата платежа. Начисление купленных товаров пользователю и списание товаров в случае отмены заказа. Аутентификация пользователей, если вы используете аутентификацию через ID пользователя. Альтернативный вариант — использование аутентификации пользователей через Xsolla Login.
Digital Distribution Hub	Обязательно	Валидация пользователей. Связывание ID транзакции со стороны Xsolla с ID транзакции в вашей системе. Передача дополнительных параметров транзакции в заказе. Начисление купленных товаров пользователю и списание их в случае отмены заказа. Подробная информация по настройке вебхуков для Digital Distribution Hub приведена в инструкции.

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

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

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

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

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

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

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

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

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

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

Название и тип вебхука	Описание
Проверка пользователей > Проверка существования пользователя (user_validation)	Отправляется на разных этапах оплаты, чтобы удостовериться, что пользователь зарегистрирован в игре.
Игровые сервисы > Объединенные вебхуки > Успешная оплата заказа (order_paid)	Данные платежа, детали транзакции и информация о купленных товарах. Используйте данные вебхука для начисления товаров пользователю.
Игровые сервисы > Объединенные вебхуки > Отмена заказа (order_canceled)	Данные отмененного платежа, детали транзакции и информацию о купленных товарах. Используйте данные вебхука для списания купленных товаров у пользователя.

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

Название и тип вебхука	Описание
Проверка пользователей > Проверка существования пользователя (user_validation)	Отправляется на разных этапах оплаты, чтобы удостовериться, что пользователь зарегистрирован в игре.
Платежи > Успешный платеж (payment)	Данные платежа и детали транзакции.
Игровые сервисы > Отдельные вебхуки > Успешная оплата заказа (order_paid)	Информация о купленных товарах. Используйте данные вебхука для начисления товаров пользователю.
Платежи > Возврат платежа (refund)	Данные платежа и детали транзакции.
Игровые сервисы > Отдельные вебхуки > Отмена заказа (order_canceled)	Информация о купленных товарах. Используйте данные вебхука для списания купленных товаров у пользователя.

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

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

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

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

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

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

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

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

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

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

Переключатель	Описание
Показывать информацию о сохраненном платежном аккаунте	Информация о сохраненном способе оплаты передается в кастомном объекте payment_account.
Показывать информацию о транзакциях сохраненными способами оплаты	В вебхуке будет передаваться информация в кастомных параметрах: saved_payment_method: 0 — сохраненный способ оплаты не используется; 1 — способ оплаты был сохранен при совершении текущей транзакции; 2 — используется ранее сохраненный способ оплаты. payment_type: 1 — единоразовый платеж; 2 — рекуррентный платеж.
Добавить объект order в вебхук	В вебхуке Успешный платеж будет передаваться информация о заказе в объекте order.
Показывать только необходимую информацию о пользователе без чувствительных данных	В вебхуке о пользователе будет передаваться только следующая информация: ID; страна.
Передавать кастомные параметры	В вебхуке будет передаваться информация о кастомных параметрах из токена.
Показывать БИН карты и последние 4 цифры ее номера	В вебхуке будет передаваться следующая информация о номере карты: первые 6 цифр в параметре card_bin; последние 4 цифры в параметре card_suffix.
Показывать бренд карты	Бренд карты, с которой была совершена оплата. Например, Mastercard или Visa.

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

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

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

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

Название вкладки для тестирования вебхуков	Название и тип вебхука
Payments and Store	Проверка пользователей > Проверка существования пользователя (user_validation)
	Игровые сервисы > Объединенные вебхуки > Успешная оплата заказа (order_paid)
	Игровые сервисы > Объединенные вебхуки > Отмена заказа (order_canceled)
Subscriptions	Проверка пользователей > Проверка существования пользователя (user_validation)
	Платежи > Успешный платеж (payment)

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

Название вкладки для тестирования вебхуков	Название и тип вебхука
Store	Игровые сервисы > Отдельные вебхуки > Успешная оплата заказа (order_paid)
	Игровые сервисы > Отдельные вебхуки > Отмена заказа (order_canceled)
Payments	Проверка пользователей > Проверка существования пользователя (user_validation)
	Платежи > Успешный платеж (payment)
Subscriptions	Проверка пользователей > Проверка существования пользователя (user_validation)
	Платежи > Успешный платеж (payment)

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

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

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

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

1. В блоке тестирования вебхуков перейдите на вкладку Payments and Store.

2. В раскрывающемся списке выберите тип товара. Если выбранный тип товара еще не настроен в Личном кабинете, нажмите:

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

3. Заполните необходимые поля:

   1. Выберите артикул товара из раскрывающегося списка и укажите его количество. Вы можете выбрать несколько товаров. Для этого нажмите + и добавьте товары в новой строке.
   2. ID пользователя — при тестировании вы можете указать любую комбинацию букв и цифр.
   3. Public user ID — ID, который известен пользователю, например, email или никнейм. Это поле отображается, если public user ID включен в вашем проекте в разделе Pay Station > Настройки.
   4. Укажите произвольное значение в поле ID заказа Xsolla.
   5. ID заявки в Xsolla — ID транзакции на стороне Xsolla. При тестировании вы можете указать любое числовое значение.
   6. Invoice ID — ID транзакции на стороне вашей игры. При тестировании вы можете указать любую комбинацию букв и цифр. Для успешной оплаты это не обязательный параметр, но вы можете передать его, чтобы связать ID транзакции на вашей стороне с ID транзакции на стороне Xsolla.
   7. Количество — сумма платежа. При тестировании вы можете указать любое числовое значение.
   8. Валюта — выберите валюту из раскрывающегося списка.

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

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

Если в вашем проекте включен public user ID, в результатах тестирования также отобразится проверка поиска пользователя.

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

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

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

Чтобы выполнить тестирование:

1. В блоке тестирования вебхуков перейдите на вкладку Subscriptions.
2. Заполните необходимые поля:
   1. ID пользователя — при тестировании вы можете указать любую комбинацию букв и цифр.
   2. ID заявки в Xsolla — ID транзакции на стороне Xsolla. При тестировании вы можете указать любое числовое значение.
   3. Public user ID — ID, который известен пользователю, например, email или никнейм. Это поле отображается, если public user ID включен в вашем проекте в разделе Pay Station > Settings > Additional settings section.
   4. Валюта — выберите валюту из раскрывающегося списка.
   5. ID плана — план подписки. Выберите план из раскрывающегося списка.
   6. Продукт подписки— выберите продукт из раскрывающегося списка (опционально).
   7. Сумма — сумма платежа. При тестировании вы можете указать любое числовое значение.
   8. Invoice ID— ID транзакции на стороне вашей игры. При тестировании вы можете указать любую комбинацию букв и цифр.Для успешной оплаты это не обязательный параметр, но вы можете передать его, чтобы связать ID транзакции на вашей стороне с ID транзакции на стороне Xsolla.
   9. Пробный период. Для тестирования покупки подписки без пробного периода или тестирования продления подписки, укажите значение 0.
3. Нажмите Тестировать вебхуки.

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

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

На стороне вашего приложения реализуйте прием вебхуков со следующих IP-адресов: 185.30.20.0/24, 185.30.21.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.

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

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

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

Чтобы сгенерировать подпись:

1. Получите тело запроса в формате JSON.
2. Конкатенируйте JSON из тела запроса и секретный ключ проекта, т. е. объедините две строки, добавив секретный ключ проекта в конец строки.
3. Примените криптографическую хэш-функцию HMAC-SHA1 к получившейся на втором шаге строке.
4. Преобразуйте результат в шестнадцатеричную строку в нижнем регистре.
5. Сравните полученную строку с подписью в заголовке Authorization HTTP-запроса.

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

POST /your_uri HTTP/1.1
Host: your.host
Accept: application/json
Content-Type: application/json
Content-Length: 165
Authorization: Signature 52eac2713985e212351610d008e7e14fae46f902
{
  "notification_type":"user_validation",
  "user":{
      "ip":"127.0.0.1",
      "phone":"18777976552",
      "email":"email@example.com",
      "id":1234567,
      "name":"Xsolla User",
      "country":"US"
  }
}

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

curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Authorization: Signature 52eac2713985e212351610d008e7e14fae46f902' \
-d '{
  "notification_type":
    "user_validation",
    "user":
      {
        "ip": "127.0.0.1",
        "phone": "18777976552",
        "email": "email@example.com",
        "id": 1234567,
        "name": "Xsolla User",
        "country": "US"
      }
    }'

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

private string ComputeHmacSha1(string jsonBody, string secretKey)
{
    // Concatenation of the JSON from the request body and the project’s secret key.
    string dataToSign = jsonBody + secretKey;
    using var hmac = new HMACSHA1(Encoding.UTF8.GetBytes(secretKey));
    byte[] hashBytes = hmac.ComputeHash(Encoding.UTF8.GetBytes(dataToSign));
    return BitConverter.ToString(hashBytes).Replace("-", "").ToLower();
}

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

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

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

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

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

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

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

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

Код	Описание
INVALID_USER	Неверный пользователь
INVALID_PARAMETER	Неверный параметр
INVALID_SIGNATURE	Подпись неверна
INCORRECT_AMOUNT	Некорректная сумма
INCORRECT_INVOICE	Неверный заказ

HTTP/1.1 400 Bad Request
{
    "error":{
        "code":"INVALID_USER",
        "message":"Invalid user"
    }
}

Вебхук	Тип оповещения	Описание
Проверка существования пользователя	user_validation	Проверка существования пользователя в игре.
Поиск пользователя	user_search	Получение информации о пользователе по публичному ID пользователя.
Успешный платеж	payment	Оповещение об успешном платеже.
Возврат платежа	refund	Оповещение об отмене платежа.
Частичный возврат платежа	partial_refund	Оповещение о частичном возврате платежа.
Транзакция отклонена при проверке AFS	afs_reject	Оповещение об отмене транзакции системой расширенного антифрода.
Обновление черного списка AFS	afs_black_list	Оповещение об изменении черного списка AFS.
Создание подписки	create_subscription	Оповещение о создании подписки.
Изменение подписки	update_subscription	Оповещение о продлении подписки или о смене каких-либо параметров внутри подписки.
Отмена подписки	cancel_subscription	Оповещение об отмене подписки.
Непродлеваемая подписка	non_renewal_subscription	Оповещение о смене статуса на непродлеваемый.
Добавление платежного аккаунта	payment_account_add	Оповещение о добавлении или сохранении платежного аккаунта.
Удаление платежного аккаунта	payment_account_remove	Оповещение об удалении платежного аккаунта.
Проверка пользователя в Web Shop	-	Отправлено из Web Shop для проверки существования пользователя в игре.
Персонализация каталога на стороне партнера	partner_side_catalog	Отправляется, когда пользователь взаимодействует с магазином.
Успешная оплата заказа	order_paid	Отправляется, когда заказ оплачен.
Отмена заказа	order_canceled	Отправляется, когда заказ отменен.
Диспут	dispute	Оповещение об открытии нового диспута.