Настройка вебхуков

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

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

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

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

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

• Успешный платеж — отправляется, когда заказ оплачен, и содержит информацию о данных платежа и детали транзакции.
• Успешная оплата заказа — отправляется, когда был получен ответ об успешной обработке вебхука Успешный платеж. Содержит информацию о купленных товарах и ID транзакции. Используйте данные вебхука для начисления товаров пользователю.
• Возврат платежа — отправляется, когда заказ был отменен, и содержит информацию о данных отмененного платежа и детали транзакции.
• Отмена заказа — отправляется, когда был получен ответ об успешной обработке вебхука Возврат платежа. Содержит информацию о купленных товарах и ID отмененной транзакции. Используйте данные вебхука для списания купленных товаров у пользователя.

• Проверка существования пользователя — отправляется на разных этапах оплаты, чтобы удостовериться, что пользователь зарегистрирован в игре.

Ниже приведена схема покупки и возврата товаров на сайте с использованием вебхуков из этого списка.

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

Настройка вебхуков в Личном кабинете

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

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

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

Тестирование вебхуков в Личном кабинете

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

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

• Store
• Payments

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

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

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

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

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

3. Укажите произвольное значение в поле ID заказа Xsolla.
4. Выберите артикул товара из раскрывающегося списка и укажите сумму. Вы можете выбрать несколько товаров одного типа. Для этого нажмите + и добавьте товары в новой строке.
5. Выберите валюту, в которой оплачивается заказ.
6. Нажмите Тестировать.

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

Примечание

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

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

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

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

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

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

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

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

Обработчик вебхуков

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

Генерация подписи

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

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

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

Отправка ответов на вебхук

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

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

Ваш обработчик вебхуков также может возвращать код 5xx при временных проблемах на вашем сервере.

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

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

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

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

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

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