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

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

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

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

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

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

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

  sequenceDiagram
    participant User
    participant GameClient as Game Client
    participant Xsolla
    participant GameServer as Game Server
    %% Item Purchase
        Note over User, GameServer: Item purchase
        User ->> GameClient: Logs in
        GameClient ->> Xsolla: Sends user authentication request
        Xsolla -->> GameClient: Returns JWT / OAuth 2.0 token
        GameClient ->> Xsolla: Sends JWT, project ID, pagination parameters
        Xsolla -->> GameClient: Returns array of items
        GameClient -->> User: Displays storefront
        User ->> GameClient: Selects item and clicks Buy
        GameClient ->> Xsolla: Creates order request
        Xsolla -->> GameClient: Returns payment token
        GameClient ->> Xsolla: Opens payment UI URL with received token
        Xsolla ->> GameServer: Sends User validation webhook
        GameServer -->> Xsolla: Returns success status code
        Xsolla -->> User: Displays payment UI
        User ->> Xsolla: Chooses payment method and clicks Pay
        Xsolla ->> GameServer: Sends Successful payment for order webhook
        GameServer ->> GameServer: Grants purchases to user
        GameServer -->> Xsolla: Returns success status code
        Xsolla -->> User: Shows successful purchase screen
    %% Refund / Chargeback
        Note over User, GameServer: Refund / Chargeback
        User ->> Xsolla: Requests refund or chargeback
        Xsolla ->> GameServer: Sends Order cancellation webhook
        GameServer ->> GameServer: Removes items from user inventory
        GameServer -->> Xsolla: Returns success status code
        Xsolla -->> User: Refunds the payment

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

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

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

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

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

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

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

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

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

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

1. В блоке тестирования вебхуков перейдите на вкладку Payments and Store.
2. В раскрывающемся списке выберите тип товара. Если выбранный тип товара еще не настроен в проекте, вы увидите кнопку для перехода к настройке товаров.
3. Заполните необходимые поля:
   • ID заказа Xsolla — ID заказа на стороне Xsolla. При тестировании вы можете указать любое числовое значение.
   • ID заявки в Xsolla — ID транзакции на стороне Xsolla. При тестировании вы можете указать любое числовое значение.
   • Предметы — товары, информацию о которых вы хотите получить в вебхуке. Выберите артикул товара из раскрывающегося списка и укажите его количество. Вы можете выбрать несколько товаров. Для этого нажмите + и добавьте товары в новой строке.
   • ID пользователя — при тестировании вы можете указать любую комбинацию букв и цифр.
   • Invoice ID — ID транзакции на стороне вашей игры. При тестировании вы можете указать любую комбинацию букв и цифр. Для успешной оплаты это не обязательный параметр, но вы можете передать его, чтобы связать ID транзакции на вашей стороне с ID транзакции на стороне Xsolla.
   • Количество — сумма платежа. При тестировании вы можете указать любое числовое значение.
   • Валюта — выберите валюту из раскрывающегося списка.
4. Нажмите Тестировать.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Логика повторной отправки вебхуков Успешный платеж и Возврат платежа описана на странице соответствующего вебхука.

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

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

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

Вы можете настроить, какие данные о товарах передаются в вебхуках Успешная оплата заказа и Отмена заказа в массиве items.

Подключение передачи дополнительных параметров

Подключите передачу дополнительных параметров, которые показывают:

• является ли товар бесплатным (is_free);
• является ли товар бонусом (is_bonus);
• входит ли товар в состав бандла (is_bundle_content).

Чтобы получать эти параметры, переключите вебхуки на версию 2 с помощью метода API Обновление информации о настройках вебхуков. В версии 1 (используется по умолчанию) эти параметры отсутствуют.

Пример массива items с дополнительными параметрами:

 1"items": [
 2      {
 3        "sku": "com.xsolla.item_new_1",
 4        "type": "bundle",
 5        "is_pre_order": false,
 6        "is_free": false,
 7        "is_bonus": false,
 8        "is_bundle_content": false,
 9        "quantity": 1,
10        "amount": "1000",
11        "promotions": []
12      },
13      {
14        "sku": "com.xsolla.gold_1",
15        "type": "virtual_currency",
16        "is_pre_order": false,
17        "is_free": false,
18        "is_bonus": false,
19        "is_bundle_content": true,
20        "quantity": 1500,
21        "amount": "[null]",
22        "promotions": []
23      }
24 ]

Отключение передачи содержимого бандла

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

В этом случае товары, входящие в состав бандла, не будут включены в массив items. В приведенном выше примере будет исключен товар с SKU com.xsolla.gold_1, являющийся частью бандла.

Пример массива items без содержимого бандла:

 1
 2"items": [
 3      {
 4        "sku": "com.xsolla.item_new_1",
 5        "type": "bundle",
 6        "is_pre_order": false,
 7        "is_free": false,
 8        "is_bonus": false,
 9        "is_bundle_content": false,
10        "quantity": 1,
11        "amount": "1000",
12        "promotions": []
13      }
14 ]

Чтобы отключить передачу содержимого бандла, обратитесь к персональному менеджеру проекта или напишите на csm@xsolla.com.