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

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

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

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

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

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

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

Вебхук обработки
платежей

Настройка серверной части

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

На стороне приложения реализован прием вебхуков со следующих IP-адресов: 185.30.20.0/24, 185.30.21.0/24, 185.30.23.0/24.
В базе данных приложения не должно быть несколько успешных транзакций с одинаковым ID.

Обратите внимание

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

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

Примечание

Xsolla использует HTTP-коды ответа для обозначения успешного или ошибочного запроса. Код 204 обозначает успешную обработку оповещения.

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

Примечание

Хотя интернет-соединение является частой причиной проблем с вебхуками, наиболее вероятной причиной является проблема в логике обработчика вебхуков.

Подпись запроса

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

Конкатенация JSON из тела запроса и секретного ключа проекта.
Применение 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"
    }
}