При разработке интеграций часто нужно принять вебхук прямо на локальном компьютере: проверить Telegram-бота, протестировать GitHub webhook, отладить callback от платёжного сервиса или посмотреть фактический HTTP-запрос, который отправляет внешний сервис.
Проблема в том, что локальное приложение обычно доступно только по адресу вроде http://localhost:3000. Внешний сервис не может отправить запрос на этот адрес: localhost существует только внутри вашего компьютера, а публичного IP-адреса, настроенного сервера или открытого порта может не быть вовсе.
В Adal для приёма вебхуков используются серверы. Сервер получает публичный HTTP-запрос, сохраняет его историю и передаёт запрос в подключённое локальное приложение через Adal CLI. Для этого не нужно открывать порты на роутере, настраивать NAT или разворачивать временный сервер.
Что получится в итоге
После настройки у вас будет постоянный публичный URL сервера в Adal. Его можно указать в настройках GitHub, Telegram, Stripe, GitLab, Shopify или любого другого сервиса, который умеет отправлять HTTP-webhook.
Когда внешний сервис отправит запрос:
Adal примет его по публичному HTTPS-адресу.
Запрос появится в истории сервера.
Adal CLI передаст запрос в ваше локальное приложение.
Локальный обработчик получит вебхук так, как будто запрос пришёл напрямую из интернета.
При этом ваше приложение продолжает работать на localhost, а компьютер не становится публично доступным.
Что потребуется
Перед началом убедитесь, что у вас есть:
аккаунт Adal;
установленный Adal CLI;
запущенное локальное приложение;
HTTP-обработчик, который может принять входящий запрос.
Для примера далее будем считать, что приложение работает по адресу:
http://localhost:3000
А запросы вебхуков должны обрабатываться по этому маршруту:
http://localhost:3000/webhooks/github
Шаг 1. Создайте сервер в Adal
Откройте панель Adal и создайте новый сервер.
При создании сервера укажите:
регион, из которого вебхуки должны приниматься;
понятное имя, например
Local GitHub development;разрешённые HTTP-методы;
при необходимости — заметку о том, для какой интеграции используется сервер.
После создания Adal выдаст серверу постоянный публичный адрес. Он выглядит примерно так:
https://your-server-id.se1.adal.cloud
Идентификатор сервера создаётся автоматически, остаётся закреплённым за сервером и не переиспользуется после его удаления.
Также, при создании сервера будет показан токен для подключения Adal CLI. Токен отображается только один раз и его нужно сохранить для последующего использования. Если вы его потеряете, то всегда можно сгенерировать новый токен.
Этот URL нужно будет указать во внешнем сервисе как адрес для доставки webhook.
Шаг 2. Добавьте локальное назначение
Сервер принимает запросы из интернета, но сам по себе не знает, куда их передавать. Для этого в Adal используется destination — назначение доставки.
Создайте destination для локального приложения и укажите адрес вашего обработчика:
http://localhost:3000
Adal сохраняет путь и query-параметры исходного запроса. Это означает, что если внешний сервис отправит webhook на адрес:
https://your-server-id.se1.adal.cloud/webhooks/github?source=test
то локальное приложение получит запрос по адресу:
http://localhost:3000/webhooks/github?source=test
Поэтому обычно достаточно указать корневой адрес локального приложения, а конкретный путь оставить в webhook URL у внешнего сервиса.
Шаг 3. Подключите Adal CLI
Чтобы Adal мог доставлять вебхуки на ваш компьютер, локальное приложение должно быть связано с Adal CLI.
При запуске CLI на компьютере, где работает ваше приложение, передайте токен напрямую в команде, например: adal-cli --token token или adal-cli -t token.
После успешного подключения CLI будет поддерживать защищённое соединение с Adal. Входящие запросы не требуют открытого входящего порта: соединение инициируется вашим компьютером наружу, а Adal использует уже установленный канал для доставки webhook.
Оставьте CLI запущенным, пока тестируете интеграцию.
Когда CLI подключён, destination становится доступным для доставки. Если соединение временно пропадёт, Adal сохранит принятый webhook и сможет доставить его после восстановления подключения в соответствии с настройками сервера и правилами повторных попыток.
Шаг 4. Укажите URL сервера во внешнем сервисе
Теперь скопируйте публичный URL сервера из Adal и добавьте нужный путь вашего обработчика.
Например, для GitHub это может быть:
https://your-server-id.se1.adal.cloud/webhooks/github
Для Telegram:
https://your-server-id.se1.adal.cloud/webhooks/telegram
Для собственного приложения или теста через curl:
https://your-server-id.se1.adal.cloud/webhooks/test
Этот URL указывается в настройках внешнего сервиса как webhook URL, callback URL или сервер для событий — точное название зависит от конкретной платформы.
Важно: не указывайте в настройках внешнего сервиса localhost, 127.0.0.1 или локальный IP-адрес из вашей сети. Эти адреса доступны только с вашего компьютера или внутри вашей локальной сети.
Шаг 5. Проверьте доставку webhook
Для быстрой проверки можно отправить тестовый HTTP-запрос самостоятельно:
curl -X POST "https://your-server-id.se1.adal.cloud/webhooks/test" \
-H "Content-Type: application/json" \
-d '{"event":"test","message":"Webhook received locally"}'
После отправки проверьте три места:
Историю сервера в Adal. Там должен появиться принятый запрос.
Историю доставки. Она покажет, была ли попытка отправки в локальное приложение успешной.
Логи локального приложения. В них должен появиться запрос на маршрут
/webhooks/test.
Если всё настроено правильно, ваше приложение получит JSON:
{
"event": "test",
"message": "Webhook received locally"
}
Как это работает
Обычная схема без публичного IP выглядит так:
Внешний сервис → публичный сервер Adal → Adal CLI → localhost
Внешний сервис отправляет webhook на публичный HTTPS-адрес Adal. Adal принимает запрос, фиксирует результат и передаёт его через подключённый CLI в ваше локальное приложение.
Ваш компьютер не принимает входящие подключения напрямую из интернета. Не требуется:
белый IP-адрес;
VPS для временного тестирования;
проброс портов на роутере;
настройка NAT;
открытие firewall-порта наружу;
отдельный домен для локальной разработки.
Это особенно удобно, если вы работаете из дома, используете мобильный интернет, корпоративную сеть, CGNAT или обычный Wi-Fi, где входящие подключения недоступны.
Как работать с разными webhook-провайдерами
Один сервер можно использовать для нескольких маршрутов внутри одного локального приложения:
https://your-server-id.se1.adal.cloud/webhooks/github
https://your-server-id.se1.adal.cloud/webhooks/telegram
https://your-server-id.se1.adal.cloud/webhooks/stripe
На локальной машине они будут доставлены соответственно на:
http://localhost:3000/webhooks/github
http://localhost:3000/webhooks/telegram
http://localhost:3000/webhooks/stripe
Это удобно, когда один проект интегрируется сразу с несколькими сервисами.
Для изолированных проектов или окружений лучше создавать отдельные серверы. Например:
Local development
Local staging
Telegram bot development
GitHub App testing
Payment callbacks development
Так проще разделять историю запросов, настройки доступа, лимиты и назначения доставки.
Что происходит, если локальное приложение выключено
Если Adal CLI не подключён или локальное приложение временно недоступно, webhook не исчезает сразу.
Adal сохраняет принятый запрос и ведёт историю попыток доставки. После восстановления CLI или локального сервиса запрос может быть повторно доставлен в зависимости от настроек сервера и правил retry.
Это отличается от прямого webhook URL на локальном компьютере: при прямом подключении внешний сервис просто не сможет достучаться до вашей машины. В Adal входящий запрос сначала принимается сервером, а уже затем доставляется в нужное назначение.
Как безопасно принимать вебхуки
Публичный URL сервера нужен для того, чтобы внешний сервис мог отправлять в него события. Но наличие публичного URL не отменяет проверку подлинности webhook внутри вашего приложения.
Для каждого провайдера стоит проверять его подпись. Например:
GitHub использует подпись
X-Hub-Signature-256;Stripe использует заголовок
Stripe-Signature;Telegram позволяет использовать секретный токен webhook;
многие сервисы передают собственный secret в заголовке или query-параметре.
Проверка подписи должна выполняться в локальном обработчике webhook до обработки события. Сервер Adal доставляет запрос в ваше приложение, но бизнес-логика приложения всё равно должна убедиться, что запрос действительно пришёл от ожидаемого провайдера.
Также не стоит публиковать URL сервера в открытом доступе без необходимости. Если адрес стал известен посторонним, создайте новый сервер и обновите URL в настройках интеграции.
Частые проблемы
Внешний сервис не принимает URL webhook
Проверьте, что вы используете полный HTTPS-адрес сервера:
https://your-server-id.se1.adal.cloud/webhooks/provider
Некоторые сервисы не принимают http://, адреса без TLS или локальные IP-адреса.
Webhook появился в Adal, но не пришёл в локальное приложение
Сначала убедитесь, что Adal CLI запущен и подключён. Затем проверьте, что destination привязан к нужному серверу и ведёт на правильный локальный адрес.
Также проверьте локальный маршрут. Если запрос приходит на:
/webhooks/github
то приложение должно действительно уметь обработать этот путь.
Локальное приложение отвечает 404
Это означает, что webhook был успешно передан снаружи в локальное приложение, но маршрут в самом приложении не найден.
Проверьте:
путь после домена сервера;
маршрут в приложении;
HTTP-метод;
настройки reverse proxy, если локально используется Docker, Nginx или другой прокси.
Локальное приложение отвечает 401 или 403
Чаще всего это происходит из-за middleware авторизации, CSRF-защиты или проверки подписи webhook.
Webhook-маршрут обычно должен быть доступен без пользовательской сессии, но при этом проверять подпись конкретного webhook-провайдера.
Запросы не доходят после перезапуска компьютера
После перезапуска нужно снова запустить локальное приложение и Adal CLI. Сервер и его публичный URL при этом остаются прежними — менять webhook URL во внешнем сервисе не нужно.
FAQ
Можно ли получать вебхуки на localhost без публичного IP?
Да. Сервер Adal принимает webhook по публичному HTTPS-адресу и передаёт его через Adal CLI в ваше локальное приложение на localhost.
Нужно ли открывать порт на роутере?
Нет. Для работы с локальными webhook через Adal не требуется проброс портов, настройка NAT или публичный IP-адрес.
Можно ли использовать один сервер для нескольких webhook?
Да. Один сервер может принимать запросы на разные пути, например /webhooks/github, /webhooks/telegram и /webhooks/stripe, а Adal передаст их в соответствующие маршруты локального приложения.
Сохраняется ли URL после перезапуска CLI?
Да. URL сервера постоянный и не меняется после перезапуска компьютера, CLI или локального приложения.
Можно ли посмотреть тело webhook до обработки приложением?
Да. История сервера позволяет видеть принятые запросы и результат их доставки. Это удобно для отладки payload, HTTP-заголовков, статусов ответа и повторных попыток.
Итог
Чтобы получать вебхуки локально без публичного IP, не нужно делать компьютер доступным из интернета. В Adal для этого создаётся сервер с постоянным HTTPS-адресом, к нему подключается destination локального приложения, а Adal CLI передаёт входящие запросы в localhost.
Вы указываете URL сервера в настройках webhook-провайдера, продолжаете разрабатывать приложение локально и при этом получаете полноценную историю запросов, доставок и ошибок в одном месте.