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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Название вебхука	Тип вебхука
Проверка существования пользователя	user_validation
Успешный платеж	payment
Отмена заказа	order_canceled
Успешная оплата заказа	order_paid

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

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

• Успешная оплата заказа (order_paid)
• Отмена заказа (order_canceled)

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

1. В блоке тестирования вебхуков перейдите на вкладку Магазин.
2. В раскрывающемся списке выберите тип товара. Если выбранный тип товара еще не настроен в Личном кабинете, нажмите:
   • Подключить – если модуль с товарами данного типа еще не подключен;
   • Настроить – если вы ранее уже подключали модуль, но не завершили настройку.
     При нажатии кнопки вы будете перенаправлены в раздел Личного кабинета, соответствующий типу выбранного товара. После создания товара вернитесь в раздел тестирования вебхуков и перейти к следующему шагу.
3. Укажите произвольное числовое значение в поле ID заказа Иксоллы.
4. Выберите артикулы товаров из раскрывающегося списка и укажите количество товаров. Вы можете выбрать несколько товаров. Для этого нажмите + и добавьте товары в новой строке.
5. Выберите валюту, в которой оплачивается заказ.
6. Нажмите Тестировать.

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

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

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

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

1. В блоке тестирования вебхуков перейдите на вкладку Payments.
2. Заполните необходимые поля:

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

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

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

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

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

На вкладке 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, 35.236.90.90, 34.102.38.178.

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

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

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

1. Осуществите конкатенацию JSON из тела запроса и секретного ключа проекта.
2. Примените SHA-1 криптографическую хэш-функцию к получившейся на первом шаге строке.

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 -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"
      }
    }'

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

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

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

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

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

Если на вебхук Проверка существования пользователя не был получен ответ или получен ответ с 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	Оповещение об открытии нового диспута.