Внешние сервисы работают независимо от графика разработчика. Они не знают, что вы закрыли ноутбук, перезапустили Docker, переключились на мобильный интернет или вообще ушли спать. Если в этот момент наступает событие, сервис просто отправляет вебхук.
Локальная среда разработки живёт совсем по другим правилам. Она, как правило, запускается только тогда, когда она нужна разработчику. Она может быть выключена, недоступна или просто ещё не готова принимать запросы.
Получается странная ситуация: внешняя система, работающая независимо от графика разработчика, пытается взаимодействовать со средой, которая по своей природе доступна лишь время от времени. Именно в этом заключается главная проблема локальной разработки с вебхуками.
Туннельные инструменты пытаются сделать локальную машину доступной из интернета. Но они по-прежнему предполагают, что в момент отправки вебхука локальная среда уже запущена и готова принять запрос. Если же ноутбук выключен, интернет пропал или приложение ещё не запущено, возникает простой вопрос: что произойдёт с запросом?
Можно поднять VPS, настроить домен, HTTPS, очередь сообщений и собственную инфраструктуру доставки. Можно даже развернуть Kubernetes. Но действительно ли для локальной отладки одного обработчика вебхуков нужна полноценная серверная инфраструктура?
Почему обычного туннеля может быть недостаточно
Сервисы туннелирования решают важную задачу: создают маршрут из публичного интернета к приложению на локальной машине.
Пока туннель работает, схема выглядит просто:
Внешний сервис → туннель → локальное приложение
Проблема появляется при разрыве соединения. Если ноутбук выключен, интернет пропал или клиент туннеля остановлен, маршрут до локального приложения больше не существует.
Некоторые отправители повторяют неудачные запросы, но полагаться только на это рискованно. Политикой повторных попыток управляет внешний сервис: он определяет их количество, интервалы и максимальное время ожидания. У одних провайдеров повторные попытки могут продолжаться несколько часов, у других их может не быть вовсе.
Сам туннель обеспечивает соединение, но не обязательно обеспечивает хранение и последующую доставку запроса. Поэтому восстановление интернета ещё не означает, что пропущенный вебхук будет отправлен повторно.
Как эту задачу решает Adal
Adal не пытается сделать локальную машину постоянно доступной. Вместо этого он разделяет две независимые задачи: приём вебхука и его доставку в локальную среду.
Внешний сервис → сервер Adal → Adal CLI → локальное приложение
Сначала запрос поступает на публичный HTTPS-адрес сервера Adal. Сервер принимает его независимо от того, подключён ли в этот момент ноутбук разработчика.
Принятый запрос сохраняется в выбранном регионе. Вместе с ним Adal сохраняет метод, путь, параметры запроса, заголовки и тело. Срок хранения определяется тарифом и отсчитывается с момента приёма запроса. Подробности описаны в документации по хранению данных.
Когда Adal CLI снова подключается к серверу, Adal передаёт ему ожидающие запросы, если в настройках сервера включена доставка накопленных запросов при подключении. Запросы ожидают доставки в пределах срока хранения, установленного тарифом.
В качестве Destination можно указать базовый адрес локального приложения, например: http://127.0.0.1:3000.
Метод, путь, параметры строки запроса, заголовки и тело передаются локальному приложению без скрытых преобразований.
Таким образом, временно недоступным может быть ноутбук, но публичный адрес для приёма вебхуков продолжает работать.
Пример: отладка платёжной интеграции в дороге
Допустим, разработчик тестирует обработку события payment.completed.
Платёжный сервис отправляет запрос:
POST /webhooks/payment.completed
Content-Type: application/json
{
"payment_id": "pay_123",
"status": "completed"
}
В этот момент ноутбук находится вне сети.
При использовании обычного туннеля запрос не сможет дойти до локального приложения. Дальнейший результат будет зависеть от того, повторит ли платёжный сервис доставку и когда именно он это сделает.
При использовании Adal последовательность будет другой:
Платёжный сервис отправляет вебхук на постоянный адрес сервера Adal.
Adal принимает и сохраняет запрос в выбранном регионе.
Разработчик снова подключается к интернету и запускает Adal CLI.
Если включена доставка накопленных запросов при подключении, CLI пересылает ожидающий запрос локальному обработчику.
Результат доставки появляется в истории доставок.
Разработчику не нужно повторно проводить тестовую оплату или ждать следующей попытки со стороны платёжного сервиса.
Та же схема полезна и в других сценариях:
при разработке Telegram-бота, когда важно не пропустить тестовое сообщение;
при отладке событий GitHub, например
pushилиpull_request;при интеграции CRM с формой на сайте;
при тестировании уведомлений о заказах, доставке или изменении подписки;
при работе с внутренним сервисом, доступным только из локальной или корпоративной сети.
Когда собственный VPS избыточен
VPS действительно может принимать вебхуки независимо от состояния ноутбука. Для постоянной инфраструктуры и сложной обработки запросов это нормальное решение.
Но один только виртуальный сервер ещё не решает задачу целиком. Обычно необходимо:
арендовать и настроить VPS;
привязать домен и настроить DNS;
установить reverse proxy;
настроить выпуск и автоматическое обновление TLS-сертификата;
настроить firewall;
развернуть приложение для приёма запросов;
реализовать хранение и повторную доставку;
настроить логи и мониторинг;
устанавливать обновления безопасности;
следить за доступностью всей системы.
Если сервер должен не только принимать, но и накапливать вебхуки во время недоступности локальной машины, понадобится очередь или другое промежуточное хранилище. Простой reverse proxy не сможет самостоятельно отложить запрос до момента подключения ноутбука.
В результате небольшая задача по отладке обработчика превращается в отдельный инфраструктурный проект.
А если есть статический IP
Можно попытаться принимать вебхуки на домашней машине. Для этого понадобятся внешний IP-адрес, настройка маршрутизатора, открытые порты, домен и HTTPS. Машина должна оставаться включённой и доступной круглосуточно.
Даже заявленный статический IP не снимает все риски. Домашние провайдеры обычно ориентированы на пользовательский доступ в интернет, а не на размещение публичных сервисов.
В практике нашей команды был случай, когда провайдер сменил тариф и вместе с ним изменил IP-адрес. Сервисы, привязанные к прежнему адресу, перестали работать. Поиск причины занял много времени: изменение IP казалось одним из наименее вероятных вариантов.
К этому добавляются перезагрузки роутера, технические работы, ограничения входящих соединений и отсутствие гарантий доступности, характерных для серверной инфраструктуры.
Когда VPS и Kubernetes всё-таки нужны
Задача этой статьи — не доказать, что собственная инфраструктура не нужна никогда.
VPS оправдан, если вы хотите постоянно запускать собственный обработчик, полностью контролировать окружение или размещать несколько связанных сервисов.
Kubernetes может быть оправдан, если у вас уже есть кластер, несколько команд, требования к масштабированию, отказоустойчивости, автоматическому развёртыванию и управлению большим количеством компонентов.
Но для локальной разработки одного обработчика вебхуков обычно не нужны:
кластер;
ingress-контроллер;
отдельная очередь;
публичный IP;
reverse proxy;
самостоятельное управление TLS-сертификатами.
Иногда задача действительно сводится к тому, чтобы получить запрос и передать его локальному приложению.
Туннель, VPS или Adal
| Критерий | Обычный туннель | Собственный VPS | Adal с CLI |
|---|---|---|---|
| Публичный HTTPS-адрес | Да, пока работает туннель | Да, после настройки | Да |
| Приём при выключенном ноутбуке | Обычно нет | Да | Да |
| Ожидание подключения локальной среды | Обычно нет | Нужно реализовать | Предусмотрено |
| Хранение истории запросов | Зависит от сервиса | Нужно реализовать | Предусмотрено |
| Администрирование сервера | Не требуется | Требуется | Не требуется |
Доставка в localhost |
Да, пока работает туннель | Нужен дополнительный механизм | Через Adal CLI |
| Подходит для постоянного размещения приложения | Обычно нет | Да | CLI предназначен прежде всего для локальной и частной среды |
Выбор зависит от задачи. Если нужна кратковременная публичная доступность локального порта, туннеля может быть достаточно. Если вы размещаете полноценное приложение, имеет смысл использовать собственную инфраструктуру. Если требуется принимать вебхуки независимо от состояния ноутбука, сохранять их и доставлять в локальную среду после подключения, можно использовать Adal.
Как начать
Для работы с Adal достаточно трёх основных шагов:
Зарегистрироваться в Adal.
Создать сервер в подходящем регионе и добавить Destination типа Adal CLI с адресом локального приложения.
Скачать Adal CLI и запустить его с полученным токеном:
adalcli --token <your-cli-token>
После подключения CLI сервер начнёт пересылать вебхуки на настроенный локальный адрес. Принятые запросы и результаты доставки можно просматривать в панели управления.
Полная последовательность настройки приведена в Quickstart-документации.
Инфраструктура должна соответствовать задаче
Вебхукам нужен стабильный публичный адрес. Локальному приложению — способ получить запрос. Но между этими требованиями не обязательно должен находиться самостоятельно настроенный VPS, а тем более Kubernetes.
Для многих сценариев разработки достаточно разделить приём и доставку: Adal принимает вебхук, пока локальная среда недоступна, а Adal CLI передаёт его приложению после того, как снова подключится.
Иногда лучший способ упростить инфраструктуру — не строить её там, где достаточно запустить Adal CLI.