Xsolla-logo

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Примечание

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

Из-за проблем с интернет-соединением или временных проблем на вашем сервере вебхуки могут теряться или задерживаться. Для решения этой проблемы Иксолла отправляет вебхуки многократно. Вебхуки отправляются в течение 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"
    }
}

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

Примечание

Тип оповещения передается в параметре notification_type.

Вебхук Продукт/Решение Тип оповещения Описание
Проверка существования пользователя Платежи 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 Оповещение о смене статуса на непродлеваемый.
Получение ключа Buy Button get_pincode Запрос на получение ключа.
Баланс пользователя: изменение вручную Внутриигровой магазин user_balance_operation Оповещение о ручном изменении баланса пользователя. Тип операции — internal.
Баланс пользователя: внутренняя операция Внутриигровой магазин user_balance_operation Оповещение о совершении платежа. Тип операции — payment.
Баланс пользователя: отмена платежа Внутриигровой магазин user_balance_operation Оповещение об отмене платежа. Тип операции — cancellation.
Баланс пользователя: активация купона Внутриигровой магазин user_balance_operation Оповещение об активации купона для получения предметов или виртуальной валюты в игре. Тип операции — coupon.
Баланс пользователя: покупка в игре Внутриигровой магазин user_balance_operation Оповещение о совершении покупки в игре. Тип операции — inGamePurchase.
Активация ключа Buy Button redeem_key Оповещение об активации ключа.
Добавление платежного аккаунта Платежи payment_account_add Оповещение о добавлении или сохранении платежного аккаунта.
Удаление платежного аккаунта Платежи payment_account_remove Оповещение об удалении платежного аккаунта.
Проверка пользователя в Веб-магазине Веб-магазин - Отправлено из Веб-магазина для проверки существования пользователя в игре.
Обработка транзакции по выплате Сервис выплат - Отправляется, когда транзакция по выплате создана и находится в обработке.
Завершение транзакции по выплате Сервис выплат - Отправляется, когда транзакция по выплате успешно выполнена.
Персонализация каталога на стороне партнера Внутриигровой магазин partner_side_catalog Отправляется, когда пользователь взаимодействует с магазином.
Успешная оплата заказа Внутриигровой магазин order_paid Отправляется, когда заказ оплачен.
Отмена заказа Внутриигровой магазин order_canceled Отправляется, когда заказ отменен.