Вебхуки — это оповещения о происходящих в системе событиях. При наступлении определенного события Xsolla отправляет HTTP-запрос к вашему приложению, в котором передаются данные о событии. Чаще всего отправляется POST-запрос в JSON-формате.
Примеры событий:
Когда происходит настроенное событие, Xsolla через вебхук оповещает вашу систему об этом. В результате вы можете:
Пример работы вебхука обработки платежей:
Видеоинструкция по интеграции вебхуков Xsolla:
Настройка вебхуков при работе с продуктами и решениями Xsolla:
Продукт/ Решение | Обязательно/ Опционально | Для чего нужны вебхуки |
---|---|---|
Payments | Обязательно |
|
In-Game Store | Обязательно |
|
Buy Button | Опционально | Для продажи ключей не требуется валидация пользователя и начисление ему товаров. Вы можете подключить вебхуки, если вы хотите получать информацию о событиях, например об оплате или отмене заказа. Если вы подключите вебхуки, важно обрабатывать все поступающие обязательные вебхуки. |
Subscriptions | Опционально | Для получения информации о создании, изменении или отмене подписки. Альтернативный вариант — запрашивать информацию с помощью API. |
Web Shop | Опционально | Для аутентификации пользователей, если вы используете аутентификацию через ID пользователя. Альтернативный вариант — использовать аутентификацию пользователей через Xsolla Login. |
Digital Distribution Hub | Опционально |
Вы можете изучить инструкцию по настройке вебхуков для Digital Distribution Hub. |
Если вы используете продукты и решения, в которых вебхуки обязательны, подключите и протестируйте вебхуки в Личном кабинете и настройте их обработку. При наступлении определенных событий вебхуки отправляются последовательно. Поэтому, если вы не обработаете какой-то из вебхуков, последующие вебхуки не будут отправлены. Список необходимых вебхуков представлен ниже.
Для полноценной работы внутриигрового магазина необходимо реализовать обработку основных вебхуков:
user_validation
) — отправляется на разных этапах оплаты,
чтобы удостовериться, что пользователь зарегистрирован в игре.payment
) —
отправляется, когда заказ оплачен, и содержит информацию о данных платежа и
детали транзакции.order_paid
) — отправляется, когда был получен ответ об успешной
обработке вебхука Успешный платеж.
Содержит информацию о купленных товарах и ID транзакции. Используйте данные
вебхука для начисления товаров пользователю.refund
) —
отправляется, когда заказ был отменен, и содержит информацию о данных
отмененного платежа и детали транзакции.order_canceled
) — отправляется, когда был получен ответ об успешной
обработке вебхука Возврат платежа.
Содержит информацию о купленных товарах и ID отмененной транзакции. Используйте
данные вебхука для списания купленных товаров у пользователя.Если вы используете персонализацию каталога товаров, реализованную на стороне вашего приложения, настройте обработку вебхука Персонализация каталога на стороне партнера.
Примечание:
Чтобы принимать реальные платежи, достаточно реализовать обработку вебхуков Успешный платеж, Успешная оплата заказа и Проверка существования пользователя и подписать лицензионный договор с Xsolla.
Для автоматического управления планами подписок необходимо реализовать обработку основных вебхуков:
user_validation
) — отправляется на разных этапах оплаты,
чтобы удостовериться, что пользователь зарегистрирован в игре.payment
) —
отправляется, когда заказ оплачен, и содержит информацию о данных платежа и
детали транзакции.create_subscription
) — отправляется, когда был получен ответ об успешной
обработке вебхука Успешный платеж или
пользователь приобрел подписку с пробным периодом. Содержит детали купленной
подписки и данные пользователя. Используйте данные вебхука для добавления
подписки пользователю.update_subscription
) — отправляется при продлении или изменении подписки,
когда был получен ответ об успешной обработке вебхука Успешный
платеж. Содержит детали купленной подписки и данные пользователя.
Используйте данные вебхука для продления подписки пользователю или изменения
параметров подписки.refund
) —
отправляется, когда заказ был отменен, и содержит информацию о данных
отмененного платежа и детали транзакции.cancel_subscription
) — отправляется, если был получен ответ об успешной
обработке вебхука Возврат платежа или
подписка была отменена по другой причине. Содержит информацию о подписке и
данные пользователя. Используйте данные вебхука для списания купленных подписок
у пользователя.Чтобы включить получение вебхуков:
https://example.com
. Вы также можете ввести
URL-адрес из инструмента для тестирования вебхуков.Внимание
Для передачи данных используется протокол HTTPS, протокол HTTP не поддерживается.
Примечание
Для тестирования вебхуков вы можете выбрать любой специализированный сайт, например webhook.site, или платформу, например ngrok.
Внимание
Вы не можете отправлять вебхуки на разные URL-адреса одновременно. Однако вы можете сначала указать в Личном кабинете URL-адрес для тестирования, а затем изменить его на боевой.
Чтобы отключить получение вебхуков:
Тестирование вебхуков помогает убедиться в корректной настройке проекта как на вашей стороне, так и на стороне Xsolla.
Вы можете протестировать получение следующих вебхуков:
Название вебхука | Тип вебхука |
---|---|
Проверка существования пользователя | user_validation |
Успешный платеж | payment |
Отмена заказа | order_canceled |
Успешная оплата заказа | order_paid |
Если вебхуки настроены успешно, ниже блока настройки вебхуков отобразится блок тестирования вебхуков.
Примечание
Если в блоке тестирования отобразилось предупреждение, что тест не пройден, проверьте настройки ответа на вебхук в вашем обработчике вебхуков. Причины ошибок в тестировании указаны в результатах тестирования.
Пример:
Для тестирования вы используете специализированный сайт webhook.site.
В разделе Тестирование ответа на неверную подпись отображается ошибка.
Это происходит, потому что Xsolla отправляет вебхук с неверной подписью и ожидает, что ваш обработчик ответит 4xx
HTTP-кодом с указанием кода ошибки INVALID_SIGNATURE
.
webhook.site отправляет 200
HTTP-код в ответ на все вебхуки, в том числе на вебхук с неверной подписью. Ожидаемый 4xx
HTTP-код не может быть получен, поэтому в результате тестирования отображается ошибка.
На вкладке Магазин вы можете протестировать работу следующих вебхуков:
order_paid
)order_canceled
)Чтобы протестировать вебхуки:
На указанный URL-адрес придут вебхуки Успешная оплата заказа и Отмена заказа с указанными данными. Ниже кнопки Тестировать отобразятся результаты тестирования каждого типа вебхука.
На вкладке Payments вы можете протестировать работу следующих вебхуков:
user_validation
)payment
)Чтобы выполнить тестирование:
На указанный URL-адрес придут вебхуки с введенными данными. Ниже кнопки Тестировать вебхуки отобразятся результаты тестирования каждого вебхука как для успешного сценария, так и для случая возникновения ошибки. Если в вашем проекте включен public user ID, в результатах тестирования также отобразится проверка поиска пользователя.
Для каждого вебхука вам необходимо настроить обработку обоих сценариев: успешного и с ошибкой.
После сохранения URL-адреса в поле Сервер для вебхуков вам будет доступен раздел Расширенные настройки, в котором вы можете дать дополнительные разрешения, чтобы получать более подробные данные в вебхуках. Для этого установите соответствующие переключатели в положение Вкл. В строке каждого разрешения указаны вебхуки, на которые повлияют изменение настроек.
Переключатель | Описание |
---|---|
Показывать информацию о сохраненном платежном аккаунте | Информация о сохраненном способе оплаты передается в кастомном объекте payment_account . |
Показывать информацию о транзакциях сохраненными способами оплаты | В вебхуке будет передаваться информация в кастомных параметрах:
|
Добавить объект order в вебхук | В вебхуке Успешный платеж будет передаваться информация о заказе в объекте order . |
Показывать только необходимую информацию о пользователе без чувствительных данных | В вебхуке о пользователе будет передаваться только следующая информация:
|
Передавать кастомные параметры | В вебхуке будет передаваться информация о кастомных параметрах из токена. |
Показывать БИН карты и последние 4 цифры ее номера | В вебхуке будет передаваться следующая информация о номере карты:
|
Показывать бренд карты | Бренд карты, с которой была совершена оплата. Например, Mastercard или Visa. |
На вкладке Subscriptions вы можете протестировать работу следующих вебхуков при управлении подписками:
user_validation
)payment
)Примечание
В Личном кабинете вы можете протестировать только базовые вебхуки Проверка существования пользователей и Успешный платеж. Для тестирования остальных вебхуков перейдите к разделам:
Примечание
Для тестирования вебхуков у вас должен быть создан хотя бы один план подписки в разделе Личный кабинет> Subscriptions > Планы подписки.
Чтобы выполнить тестирование:
0
.На указанный URL-адрес придут вебхуки с введенными данными. Ниже кнопки Тестировать вебхуки отобразятся результаты тестирования каждого вебхука как для успешного сценария, так и для случая возникновения ошибки.
Обработчик вебхуков – это программный код, который позволяет принимать поступающие вебхуки на указанный URL-адрес, генерировать подпись и отправлять ответ на вебхук на сервер Xsolla.
Примечание
Вы можете использовать библиотеку Pay Station PHP SDK, которая содержит готовые классы для обработки вебхуков.
На стороне вашего приложения реализуйте прием вебхуков со следующих IP-адресов:
185.30.20.0/24
, 185.30.21.0/24
, 185.30.23.0/24
, 34.102.38.178
,
34.94.43.207
, 35.236.73.234
, 34.94.69.44
, 34.102.22.197
.
Ограничения:
При получении вебхука необходимо обеспечить безопасность передачи данных. Для этого из данных вебхука необходимо сгенерировать подпись и проверить, что она совпадает с подписью, отправленной в заголовке HTTP-запроса. Чтобы сгенерировать подпись:
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"
}
}'
Чтобы подтвердить получение вебхука, ваш сервер должен вернуть:
200
, 201
, или 204
HTTP-код в случае успешного ответа.400
HTTP-код с описанием
проблемы, если указанный пользователь не был найден или если передана
недействительная подпись. Ваш обработчик вебхуков также может возвращать 5xx
HTTP-код при временных проблемах на вашем сервере.Если на вебхуки Успешная
оплата заказа и Отмена
заказа не был получен ответ или получен ответ с кодом 5xx
, осуществляется
повторная отправка вебхуков по следующему расписанию:
Максимально осуществляется 20 попыток отправки вебхуков в течение 12 часов с
момента первой попытки. Если на вебхук Успешный платеж или Возврат платежа не был получен ответ или
получен ответ с 5xx
HTTP-кодом, также осуществляется повторная отправка
вебхуков через увеличивающийся временной интервал. Максимально осуществляется
12 попыток в течение 12 часов.
Внимание
Если возврат платежа был инициирован Xsolla и в ответе на вебхук Возврат платежа пришел ответ с `5xx` HTTP-кодом, платеж все равно будет возвращен.
Если на вебхук Проверка
существования пользователя не был получен ответ или получен ответ с 400
или 5xx
HTTP-кодом, повторная отправка вебхукаПроверка существования пользователя не осуществляется.
Пользователь увидит ошибку, вебхуки Успешный платеж и Успешная оплата заказа
отправлены не будут.
Коды ошибок для 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 |
Оповещение о смене статуса на непродлеваемый. |
Добавление платежного аккаунта | payment_account_add |
Оповещение о добавлении или сохранении платежного аккаунта. |
Удаление платежного аккаунта | payment_account_remove |
Оповещение об удалении платежного аккаунта. |
Проверка пользователя в Web Shop | - |
Отправлено из Web Shop для проверки существования пользователя в игре. |
Персонализация каталога на стороне партнера | partner_side_catalog |
Отправляется, когда пользователь взаимодействует с магазином. |
Успешная оплата заказа | order_paid |
Отправляется, когда заказ оплачен. |
Отмена заказа | order_canceled |
Отправляется, когда заказ отменен. |
Диспут | dispute |
Оповещение об открытии нового диспута. |