Интеграция с webhook в 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 будет отправлять на ваш webhook-эндпоинт запросы двух типов:

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

Запрос верификации

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

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

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

{}

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

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

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

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

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

Для production-событий используйте поле 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. ID события может быть любой строкой — главное, чтобы ID события на вашем сервере обработки вебхуков совпадал с тем, что вы указали в дашборде Adapty. Оставлять поле ID события пустым для включённых событий нельзя.

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 повторяет доставку с экспоненциальной задержкой. Первая попытка происходит примерно через 1 минуту после первого сбоя, каждая следующая — вдвое позже. Всего до 9 попыток в течение 24 часов. Рекомендуем настроить вебхук так, чтобы перед ответом он выполнял только базовую валидацию тела события от Adapty. Если сервер не может обработать событие и вы не хотите повторных попыток от Adapty, используйте код ответа в диапазоне 200–404. Ресурсоёмкие задачи обрабатывайте асинхронно и отвечайте Adapty как можно быстрее. Если Adapty не получит ответ в течение 10 секунд, попытка считается неудачной и будет повторена.