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

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

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

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

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

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

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

• На стороне приложения реализован прием вебхуков со следующих 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.

• Сформированная подпись запроса должна совпадать с подписью, отправленной в HTTP-заголовке.
• В случае возникновения ошибки вы должны вернуть код 400 (например, когда отсутствует обязательный параметр или пополнение баланса невозможно). В случае временной серверной ошибки — код 500.

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

Подпись обеспечивает безопасность передачи данных. Генерация подписи состоит из следующих шагов:

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

Коды ошибок для 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	Оповещение об удалении платежного аккаунта.
Проверка пользователя в Веб-магазине	-	Отправлено из Веб-магазина для проверки существования пользователя в игре.
Обработка транзакции по выплате	-	Отправляется, когда транзакция по выплате создана и находится в обработке.
Завершение транзакции по выплате	-	Отправляется, когда транзакция по выплате успешно выполнена.
Персонализация каталога на стороне партнера	partner_side_catalog	Отправляется, когда пользователь взаимодействует с магазином.
Успешная оплата заказа	order_paid	Отправляется, когда заказ оплачен.
Отмена заказа	order_canceled	Отправляется, когда заказ отменен.