Интеграция с вебхуком в Adapty состоит из следующих шагов:

1. Вы настраиваете свой эндпоинт:
   1. Убедитесь, что ваш сервер может обрабатывать запросы от Adapty с заголовком Content-Type со значением application/json.
   2. Настройте сервер так, чтобы он принимал верификационный запрос от Adapty и отвечал любым статусом 2xx и телом в формате JSON.
   3. Обрабатывайте события подписок после подтверждения соединения.
2. Вы настраиваете и включаете интеграцию с вебхуком в дашборде Adapty. Также можно сопоставить события Adapty с собственными названиями событий. Рекомендуем сначала протестировать в среде Sandbox, прежде чем переходить на продакшн.
3. Adapty отправляет верификационный запрос на ваш сервер.
4. Ваш сервер отвечает статусом 2XX и телом в формате JSON.
5. Как только Adapty получает корректный ответ, он начинает отправлять события подписок.

Настройка сервера для обработки запросов Adapty

Adapty будет отправлять на ваш вебхук-эндпоинт два типа запросов:

1. Верификационный запрос: первоначальный запрос для проверки корректности настройки соединения. Он не содержит никаких событий и отправляется в момент нажатия кнопки Save в настройках интеграции с вебхуком в дашборде Adapty. Чтобы подтвердить успешное получение запроса, ваш эндпоинт должен ответить верификационным ответом.
2. Событие подписки: стандартный запрос, который сервер Adapty отправляет каждый раз при создании нового события. Ваш сервер не обязан отвечать каким-либо специальным ответом — достаточно вернуть стандартный HTTP-ответ с кодом 200, если сообщение успешно получено.

Верификационный запрос

После включения интеграции с вебхуком в дашборде Adapty отправит POST-запрос верификации с пустым JSON-объектом {} в теле.

Настройте эндпоинт с заголовком Content-Type равным application/json, то есть ваш сервер должен ожидать входящие вебхук-запросы с полезной нагрузкой в формате JSON.

Ваш сервер должен ответить статусом 2xx и любым корректным JSON, например:

{}

Как только Adapty получит верификационный ответ в правильном формате и со статусом 2xx, интеграция с вебхуком будет полностью настроена.

События подписок

События подписок отправляются с заголовком Content-Type равным application/json и содержат данные события в формате JSON. Описание возможных типов событий и структур запросов см. в разделе Типы и поля событий вебхука.

Настройка интеграции с вебхуком в дашборде Adapty

В Adapty можно настроить отдельные потоки для продакшн-событий и тестовых событий, поступающих из песочницы Apple или Stripe либо из тестового аккаунта Google.

Для продакшн-событий используйте поле Production endpoint URL, указав URL, на который будут отправляться колбэки. Также заполните поле Authorization header value for production endpoint — заголовок, с помощью которого ваш сервер будет аутентифицировать события от Adapty. Обратите внимание: значение из поля Authorization header value for production endpoint будет использоваться как заголовок Authorization точно в том виде, в котором оно указано, без каких-либо изменений.

Для тестовых событий используйте поля Sandbox endpoint URL и Authorization header value for sandbox endpoint соответственно.

Чтобы настроить интеграцию с вебхуком:

1. Откройте раздел Integrations -> Webhook в дашборде Adapty.

2. Включите тумблер, чтобы активировать интеграцию.

3. Заполните поля интеграции:

   Поле	Описание
   Production endpoint URL	URL, на который Adapty будет отправлять HTTP POST-запросы для продакшн-событий.
   Authorization header value for production endpoint	Заголовок, который ваш сервер будет использовать для аутентификации запросов от Adapty в продакшне. Обратите внимание: значение из этого поля будет использоваться как заголовок Authorization точно в том виде, в котором оно указано, без каких-либо изменений. Не является обязательным, но настоятельно рекомендуется для повышения безопасности.

   Для тестирования в среде песочницы доступны ещё два поля:

   Поле для тестирования	Описание
   Sandbox endpoint URL	URL, на который Adapty будет отправлять HTTP POST-запросы для событий в среде песочницы.
   Authorization header value for sandbox endpoint	Заголовок, который ваш сервер будет использовать для аутентификации запросов от Adapty при тестировании в среде песочницы. Обратите внимание: значение из этого поля будет использоваться как заголовок Authorization точно в том виде, в котором оно указано, без каких-либо изменений. Не является обязательным, но настоятельно рекомендуется для повышения безопасности.

4. (необязательно) Выберите события, которые хотите получать, и при необходимости переименуйте их. Ознакомьтесь с разделом Потоки событий, чтобы узнать, какие события срабатывают в разных ситуациях.

   Если идентификаторы событий в вашей системе отличаются от тех, что используются в Adapty, оставьте свои идентификаторы без изменений и замените стандартные идентификаторы Adapty своими в разделе Events names на странице Integrations -> Webhooks.

   Идентификатор события может быть любой строкой — главное, чтобы идентификатор в вашем сервере обработки вебхуков совпадал с тем, что указан в дашборде Adapty. Для включённых событий поле идентификатора не может быть пустым.

5. Дополнительные поля и настройки необязательны — используйте их по мере необходимости:

   Настройка	Описание
   Send Trial Price	При включении Adapty будет добавлять цену подписки в поля price_local и price_usd для события Trial Started.
   Exclude Historical Events	Позволяет исключить события, произошедшие до установки пользователем приложения с Adapty SDK. Это предотвращает дублирование событий и обеспечивает точность отчётов. Например, если пользователь активировал месячную подписку 10 января, а обновил приложение с Adapty SDK 6 марта, Adapty пропустит события до 6 марта и сохранит последующие.
   Send user attributes	Включите этот параметр, чтобы отправлять пользовательские атрибуты, например языковые настройки. Эти атрибуты будут отображаться в поле user_attributes. Подробнее см. в разделе Поля событий.
   Send attribution	Включите этот параметр, чтобы добавлять информацию об атрибуции (например, данные AppsFlyer) в поле attributions. Подробнее см. в разделе Данные атрибуции.
   Send Play Store purchase token	Включите этот параметр, чтобы получать токен покупки из Play Store, необходимый для повторной валидации покупки. При включении в событие будет добавлен параметр play_store_purchase_token. Подробнее о его содержимом см. в разделе Токен покупки Play Store.

6. Не забудьте нажать кнопку Save, чтобы сохранить изменения.

В момент нажатия кнопки Save Adapty отправит верификационный запрос и будет ожидать ответа от вашего сервера.

Выбор событий и сопоставление названий

Выберите события, которые хотите получать на свой сервер, включив тумблер рядом с каждым из них. Если названия событий в вашей системе отличаются от тех, что используются в Adapty, и вы хотите сохранить свои названия, настройте сопоставление — замените стандартные названия событий Adapty своими в разделе Events names на странице Integrations -> Webhooks.

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

Обработка событий вебхука

Как правило, вебхуки доставляются в течение 5–60 секунд после возникновения события. Исключение составляют события отмены — они могут доставляться с задержкой до 2 часов после отмены подписки пользователем.

Если код статуса ответа вашего сервера выходит за пределы диапазона 200–404, Adapty будет повторно пытаться отправить событие — до 9 раз в течение 24 часов с экспоненциальной задержкой. Рекомендуем настроить вебхук так, чтобы он выполнял лишь базовую валидацию тела события от Adapty перед ответом. Если ваш сервер не может обработать событие и вы не хотите повторных попыток со стороны Adapty, используйте код статуса в диапазоне 200–404. Кроме того, выполняйте ресурсоёмкие задачи асинхронно и быстро отвечайте Adapty. Если Adapty не получит ответ в течение 10 секунд, попытка будет считаться неудачной и будет предпринята повторная.