Интеграция с 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 часов после того, как пользователь отменил подписку.

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

События не гарантированно поступают в порядке очерёдности — см. раздел Поля события о том, как самостоятельно упорядочить и дедуплицировать их.

Приостановленная доставка после повторных сбоев

Когда большинство последних запросов к вашему эндпоинту завершаются с ошибкой, Adapty приостанавливает доставку вебхуков для вашего приложения. Ошибкой здесь считается то же, что и при повторных попытках: статус ответа вне диапазона 200–404, ошибка соединения или отсутствие ответа в течение 10 секунд. Пока доставка приостановлена, Adapty не отправляет новые события на ваш эндпоинт и не повторяет их позднее. Такие события получают статус Sending failed, даже если ваш сервер не получил ни одного запроса. После периода ожидания Adapty отправляет следующее событие для проверки эндпоинта. Если доставка проходит успешно — нормальная работа возобновляется. Если нет — доставка снова приостанавливается, но уже с более долгим периодом ожидания.

Запрос верификации, который Adapty отправляет при нажатии Save, не проходит через этот конвейер доставки, поэтому он может завершиться успешно, даже если доставка приостановлена.

Чтобы доставка не прерывалась, отвечайте статусом 2xx на каждое событие — в том числе на те, которые ваш сервер пока не может сопоставить ни с одним пользователем, — и обрабатывайте их на своей стороне.