Как принять первый вебхук за пять минут

Вебхуки удобно тестировать, когда отправитель уже может обратиться к вашему приложению по публичному HTTPS URL. Но у нового проекта такого адреса обычно ещё нет: обработчик работает на ноутбуке, машина находится за NAT, домен не настроен, а менять конфигурацию существующего сервера рискованно или просто некогда.

Конечно, эту задачу можно решить самостоятельно: развернуть сервис на облачной платформе или VPS, настроить DNS, TLS и reverse proxy либо открыть доступ к локальной среде через туннель. Это нормальные варианты, особенно если они уже встроены в инфраструктуру команды.

Но иногда инфраструктура — не цель задачи. Нужно узнать, отправляет ли внешний сервис вебхук, увидеть его заголовки и тело, проверить обработчик или показать работающий сценарий. В таком случае можно начать с Сервера Adal.

Тот же маршрут применим не только к разработке. Adal можно оставить в production как публичный слой приёма и надёжной доставки запросов в приложение, которое работает в закрытой сети и не принимает входящие соединения из интернета.

Почему открытие порта не всегда решает задачу

Иногда можно. Если у команды уже есть публичный сервер и настроенный reverse proxy, новый hostname можно направить на отдельный обработчик через тот же порт 443. TLS-сертификаты не привязаны к конкретному порту, а SNI позволяет обслуживать на одном адресе несколько доменов.

Для локальной машины ситуация обычно сложнее. Нужны доступный извне адрес, правило маршрутизации через NAT или firewall, DNS и корректно настроенный HTTPS. Запустить HTTPS можно и на нестандартном порту, но не каждый webhook-провайдер разрешает URL с таким портом. Кроме того, изменение работающего reverse proxy или маршрутизатора перед демо создаёт ненужный риск.

Adal снимает именно эту часть задачи: Сервер уже имеет публичный HTTPS URL, а доступ к локальному приложению при необходимости организует Adal CLI через исходящее соединение.

Что можно успеть за пять минут

Каждый Сервер Adal получает постоянный публичный HTTPS URL. На него можно отправить запрос из внешнего сервиса или обычным curl, а затем открыть принятый Request в панели Adal.

Минимальный сценарий выглядит так:

1. Войдите в Adal или создайте аккаунт. При регистрации по email подтвердите адрес электронной почты; при входе через Google или GitHub этот шаг не требуется.

2. Создайте Сервер: выберите регион, задайте понятное имя и сохраните настройки.

3. Скопируйте его публичный Ingest URL.

4. Укажите этот URL в сервисе-отправителе или отправьте тестовый запрос самостоятельно.

5. Откройте раздел Requests и изучите полученный запрос.

Например:

В интерфейсе можно увидеть метод, путь, query-параметры, заголовки, тело, время получения и состояние доставки. Если хранение запросов включено, Request остаётся доступен в пределах retention-периода текущего плана.

Пять минут здесь — ориентир для получения URL и первого запроса, а не гарантия для любой интеграции. Некоторые внешние сервисы требуют отдельного подтверждения webhook URL, настройки подписи или дополнительных прав доступа.

Когда понадобится локальный обработчик

Чтобы только принять и посмотреть вебхук, локальное приложение не обязательно. Его можно подключить позже через Adal CLI:

Для этого создайте Destination типа Adal CLI, укажите локальный адрес обработчика, например http://127.0.0.1:3000, и запустите CLI с выданным токеном. CLI устанавливает исходящее защищённое соединение с Adal, поэтому локальному приложению не нужны публичный IP и открытый входящий порт.

Так приём вебхука и готовность обработчика становятся двумя отдельными задачами. Можно сначала зафиксировать реальный запрос, затем написать или исправить код и после этого повторно отправить сохранённый Request через Replay. Replay создаёт новый Request на основе исходного и не изменяет оригинал.

Хакатон: не тратить первый час на сеть

На хакатоне инфраструктурная настройка конкурирует за время с самой идеей проекта. Кроме того, разные части команды часто становятся готовы не одновременно: один участник подключает внешний API, второй пишет обработчик, третий собирает интерфейс.

Сервер Adal можно сразу указать как webhook URL внешнего сервиса. После этого команда видит, какие события действительно приходят, и может работать с реальными payload, пока обработчик ещё находится в разработке. Когда код готов, к потоку подключается локальный Destination через Adal CLI.

Это особенно полезно, если отправитель генерирует событие только после редкого или трудоёмкого действия. Сохранённый Request можно воспроизводить через Replay, не повторяя весь внешний сценарий после каждого изменения кода.

MVP: отделить интеграцию от первого развёртывания

В MVP часто проверяется одна ключевая цепочка: например, оплата завершена, форма отправлена или задача создана во внешней системе. Поднимать ради неё законченный входной контур может быть преждевременно, особенно если архитектура приложения ещё меняется.

Постоянный URL Сервера Adal можно настроить у отправителя один раз, а Destinations менять по мере развития проекта: сначала локальная машина разработчика, затем тестовое окружение, позже — внутренний production-сервис. Входящий адрес при этом остаётся прежним, пока существует Сервер.

Так интеграция растёт вместе с проектом: быстрый маршрут, созданный для MVP, может стать постоянным каналом доставки в закрытую инфраструктуру.

Proof-of-concept: проверить конкретную гипотезу

Задача proof-of-concept — не показать законченный продукт, а снять техническую неопределённость. Для интеграции с вебхуками такой неопределённостью может быть один из вопросов:

• отправляет ли система нужное событие в реальном сценарии;

• присутствуют ли в payload необходимые поля;

• какие заголовки и query-параметры приходят на практике;

• соответствует ли подпись запроса документации провайдера;

• способен ли будущий обработчик принять фактический размер и формат данных;

• можно ли доставить запрос в закрытое окружение без публичного входящего подключения.

Adal позволяет сохранить исходный Request как наблюдаемый результат эксперимента. После этого один и тот же запрос можно использовать при доработке обработчика, вместо того чтобы каждый раз заново воспроизводить событие у провайдера.

В этом и состоит отличие от общего тестирования приложения: proof-of-concept должен дать ответ на заранее сформулированный технический вопрос. Принятый Request и история его доставки становятся проверяемыми данными, на которых основан этот ответ.

Демо клиенту: сделать показ менее зависимым от ноутбука

У демо другая цель: не исследовать неизвестность, а устойчиво показать понятный пользовательский сценарий. Здесь особенно неприятны сбои, не связанные с продуктовой логикой: изменившийся адрес туннеля, закрытый ноутбук, перезапущенный локальный сервер или ошибка в последней сборке обработчика.

Публичный URL Сервера Adal можно заранее зарегистрировать у внешнего сервиса и не менять перед встречей. Во время демонстрации в панели видно, что событие действительно пришло, когда оно было получено и чем завершилась доставка в Destination.

Если локальный обработчик в этот момент недоступен, сам факт получения вебхука всё равно можно проверить в Adal при включённом хранении. После восстановления приложения запрос можно отправить снова с помощью Replay или повторить конкретную доставку через manual retry — в зависимости от того, нужно ли создать новый Request или заново выполнить существующую доставку.

Для демонстраций лучше использовать тестовые данные. Если в webhook payload могут находиться персональные данные, секреты или другая чувствительная информация, заранее проверьте настройки хранения, выбранный регион, retention и то, что допустимо показывать на общем экране.

Production: доставка запросов в закрытую сеть

Adal CLI можно запускать не только на ноутбуке разработчика. Он может постоянно работать внутри частной сети, где ему доступен внутренний сервис по локальному IP или private hostname.

Например, маршрут платёжного вебхука может выглядеть так:

Adal CLI сам устанавливает защищённое исходящее соединение с Adal. Поэтому на маршрутизаторе или firewall не нужно открывать входящий порт к платёжному серверу, а самому серверу не нужны публичный IP, домен и TLS-сертификат для приёма запросов из интернета.

Внешний сервис отправляет вебхук на публичный HTTPS URL Сервера Adal. Adal принимает Request, сохраняет его при включённом хранении и передаёт через подключённый CLI во внутренний Destination. В интерфейсе остаются видны время получения, содержимое запроса, состояние доставки и результаты отдельных попыток.

Платёжный сервер при этом недоступен из интернета напрямую: его публичный IP и входящие порты нельзя сканировать или атаковать, потому что они не опубликованы. Публичное соединение завершается на инфраструктуре Adal, что уменьшает прямую внешнюю поверхность атаки внутреннего сервиса.

Adal также может защищать Destination от резких всплесков и DDoS-нагрузки с помощью настройки Minimum delivery interval. Значение задаётся в миллисекундах. После отправки каждого запроса в Destination Adal выжидает указанный интервал и только затем отправляет следующий.

Например, при значении 100 пауза между отправками составит 100 миллисекунд. Если Adal примет 100 запросов за одну секунду, внутренний сервис будет получать примерно по 10 запросов в секунду, а доставка всей серии займёт около 10 секунд. Скорость доставки в этом примере уменьшится примерно в десять раз, зато сервер пользователя не получит такой же burst, какой пришёл на публичный Сервер Adal.

Проверка подписи отправителя и другие прикладные меры безопасности при этом по-прежнему нужны: ограничение темпа доставки защищает доступность обработчика, но не определяет, является ли конкретный запрос легитимным.

Закрытый production-контур может быть нужен и по другим причинам:

• политика безопасности запрещает входящие соединения из интернета;

• приложение работает on-premises, в private cloud или в изолированном сетевом сегменте;

• у сервиса нет публичного IP и правила NAT нельзя или нецелесообразно менять;

• внутренний обработчик не должен самостоятельно завершать TLS и обслуживать публичный трафик;

• legacy-приложение доступно только по локальному адресу;

• команда хочет централизованно принимать запросы и доставлять их в несколько внутренних Destinations;

• внутренний сервис нужно защитить от резких всплесков входящих запросов с помощью управляемого интервала доставки;

• при временной недоступности внутреннего сервиса важно сохранить наблюдаемость и управлять повторными попытками доставки.

Если CLI временно отключён, поведение накопленных Requests определяется настройками Сервера, Destination и retention. При включённой опции Deliver pending requests on connect ожидающие Requests передаются после восстановления соединения.

Таким образом, Adal — не только инструмент для просмотра тестовых вебхуков. Его можно использовать как production-ready слой между публичным интернетом и закрытой системой: принять запрос на постоянный HTTPS URL, сохранить его, показать историю и предсказуемо доставить во внутренний сервис без открытого входящего порта.

Тестирование собственного отправителя вебхуков

Adal полезен не только принимающей стороне. Если ваше приложение само отправляет вебхуки клиентам, временно укажите Сервер Adal в качестве получателя. Так можно проверить фактический HTTP-запрос, который покидает вашу систему:

• метод, путь и query-параметры;

• заголовки, включая тип содержимого и подпись;

• тело запроса и его размер;

• точное время получения;

• интервалы между запросами во время серии событий.

Это помогает находить расхождения между документацией интеграции и реальным поведением отправителя: неверное имя заголовка, неожиданную сериализацию JSON, пропущенное поле или слишком частую повторную отправку.

Время получения показывает, когда запрос достиг Adal. Чтобы измерять полную задержку от создания события до приёма, добавьте timestamp и идентификатор события на стороне отправителя. Одних серверных отметок получения недостаточно для точного end-to-end измерения.

Проверка по регионам

Сервер создаётся в выбранном регионе, поэтому несколько Серверов можно использовать для сравнительного теста доставки. Например, управляемый вами отправитель может отправить одинаковые запросы в разные регионы, а вы — сопоставить время получения и результаты доставки.

Такой эксперимент полезен для предварительной оценки маршрута, но его не стоит выдавать за строгий сетевой benchmark. Для корректного сравнения нужны одинаковые условия, синхронизированное время на отправителе, идентификаторы запросов и серия измерений, а не один webhook.

Ещё несколько практических сценариев

Изучение интеграции до написания кода

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

Регрессионная проверка после изменения обработчика

Сохранённый Request можно воспроизвести после рефакторинга, обновления библиотеки или изменения схемы данных. Это не заменяет автоматические тесты, но даёт быстрый способ проверить код на реальном примере от внешнего сервиса.

Сравнение старой и новой версии

Один Сервер может доставлять Request в несколько Destinations в пределах ограничений плана. Это позволяет направить одинаковый входящий вебхук в текущий и новый обработчики, а затем отдельно изучить результат каждой доставки.

Совместная диагностика с внешним сервисом

Когда интеграция не работает, спор часто начинается с вопроса: «Запрос вообще был отправлен?» Сохранённый Request, время получения, заголовки и история доставки помогают разделить проблему отправки, приёма и обработки и обсуждать конкретные данные.

Тестирование событий, которые трудно повторить

Некоторые вебхуки возникают после длинной последовательности действий или зависят от внешнего процесса. Приняв такой запрос один раз, команда может использовать Replay во время разработки, не воспроизводя всю последовательность для каждой проверки.

От первого теста до production

Для тестового проекта Adal даёт быстрый способ получить публичный HTTPS URL, увидеть настоящий вебхук и передать его обработчику без отдельной сетевой настройки. По мере развития проекта тот же Сервер можно использовать для доставки в тестовые, внутренние и production-окружения.

С Adal этот путь выглядит так:

Начать можно с краткого руководства Adal. Для доставки в локальное окружение используйте Adal CLI, а правила хранения и удаления данных описаны в документации по retention.