Обзор
Adal — инфраструктура для вебхуков: приём, просмотр, временное хранение, пересылка, повторные попытки и повторная отправка HTTP-запросов вебхуков с сохранением запроса в том виде, в каком он был получен.
Adal создаёт наблюдаемый слой между внешним отправителем и вашим приложением: принимает запрос по постоянному публичному URL, показывает его исходное содержимое и передаёт принятые Запросы настроенным Получателям.
Основная модель состоит из четырёх сущностей. Сервер (Server) принимает вебхук, принятый вебхук становится Запросом (Request), Получатель (Destination) задаёт цель пересылки, а Доставка (Delivery) связывает конкретный Запрос с конкретным Получателем.
Важно: Adal сохраняет исходные HTTP-метод, URI, заголовки и тело. Он не дополняет Запрос бизнес-данными, не изменяет его содержимое и не принимает решения за ваше приложение.
Как связаны основные сущности
Внешний сервис → Сервер Adal → Запрос
├── Доставка → Получатель A
└── Доставка → Получатель B
Внешний сервис отправляет вебхук на URL сервера Adal.
Сервер проверяет условия приёма и сохраняет принятый HTTP-запрос как Запрос Adal.
Для каждого настроенного Получателя создаётся отдельная Доставка.
Adal или Adal CLI выполняет попытку доставки и сохраняет её результат.
После временной ошибки Adal может выполнить дополнительные попытки по расписанию Получателя.
Сервер
└── Запрос #1
├── Доставка → Получатель A → Попытка → 2xx
└── Доставка → Получатель B → Попытка → Ошибка → Повтор
Один Сервер принимает много Запросов. Один Запрос может направляться нескольким Получателям, поэтому у него может быть несколько независимых Доставок. У каждой Доставки — собственная история попыток и конечный результат.
Сервер (Server)
Сервер — публичная точка входа для вебхуков. У него есть постоянный региональный URL, который указывается во внешнем сервисе, например GitHub, Stripe или Telegram.
Сервер определяет:
регион приёма и обработки запросов;
разрешённые HTTP-методы;
срок хранения в пределах возможностей тарифа и настроек;
набор Получателей, которым будут доставляться принятые Запросы.
URL принимает запросы не только на корневой адрес, но и на вложенные пути со строкой запроса. Сервер без Получателей всё равно может принимать вебхуки для просмотра, если включено хранение запросов, но не будет автоматически пересылать их дальше.
Запрос (Request)
Запрос — запись об отдельном HTTP-запросе, поступившем на Сервер Adal. Каждый принятый вебхук становится самостоятельным Запросом с собственным идентификатором, временем приёма, статусом и датой удаления, если он сохранён.
Сохранённый Запрос содержит данные, необходимые для просмотра и доставки:
HTTP-метод, полный URI, путь и параметры строки запроса;
заголовки и тело;
время приёма, размер и технические сведения;
связанные Доставки и историю их попыток.
Принятие не равно доставке. Наличие Запроса означает, что Adal принял вебхук. Оно не означает, что какой-либо Получатель уже получил или обработал его.
Если входящий запрос не соответствует условиям Сервера или аккаунта, он может быть отклонён до сохранения полного содержимого. Для отклонённого запроса остаются только минимальные сведения для диагностики; Доставки не создаются.
Получатель (Destination)
Получатель — настроенная цель, куда Adal должен пересылать Запросы Сервера. Получатель относится к одному Серверу и хранит параметры соединения и повторных попыток для своего маршрута доставки.
Direct HTTP
Adal отправляет Запрос из своей инфраструктуры прямо на публичный HTTP- или HTTPS-адрес. Этот вариант подходит для доступного из интернета приложения и не требует запущенного Adal CLI.
Adal CLI
Adal передаёт Запрос по защищённому исходящему соединению подключённому CLI, а CLI отправляет его локальному или приватному сервису. Приложению не нужен публичный IP-адрес или временный туннель.
Отправитель → Сервер Adal → Adal CLI → http://127.0.0.1:3000
Несколько Получателей образуют fan-out: один Запрос доставляется в несколько систем. Ошибка одного маршрута не отменяет успешную Доставку по другому.
Доставка и попытка доставки
Доставка описывает передачу конкретного Запроса конкретному Получателю. Попытка доставки — один фактический сетевой вызов внутри этой Доставки. Первая отправка и каждый автоматический или ручной Повтор сохраняются в её истории.
Для Direct HTTP запрос отправляет Adal, а для локального маршрута — подключённый Adal CLI. Получателю передаются сохранённые метод, URI, заголовки и тело запроса.
Попытка успешна, когда Adal получает HTTP-ответ со статусом 2xx. Статусы 4xx и 5xx, сетевые ошибки и тайм-ауты считаются неуспешными.
Важно: Успешная Доставка означает только то, что Adal получил ожидаемый HTTP-ответ Получателя. Она не доказывает, что приложение завершило бизнес-операцию, сохранило данные или выполнило действие во внешней системе.
Повторная попытка и Replay
Оба действия отправляют данные снова, но работают на разных уровнях:
| Действие | Что происходит | Куда отправляется |
|---|---|---|
| Повтор Доставки | В существующей Доставке создаётся новая попытка | Тому же конкретному Получателю |
| Replay Запроса | Из сохранённых данных создаётся новый Запрос | Текущим Получателям Сервера |
Replay → Новый Запрос → Новые Доставки → Текущие Получатели
Автоматические Повторы выполняются по настройкам каждого Получателя. Ручной Повтор снова выполняет одну конкретную Доставку. Replay заново проводит сохранённый Запрос через текущий маршрут Сервера, например после изменения приложения или конфигурации Получателей.
Повтор может выполняться после потери ответа или тайм-аута, когда приложение уже успело совершить действие. Поэтому Повторы и Replay могут создавать дубликаты и повторные побочные эффекты. Доставка «ровно один раз» не гарантируется.
Регион и срок хранения
Регион выбирается при создании Сервера, входит в его публичный URL и определяет, где Adal принимает и обрабатывает Запросы. Данные Запросов и Доставок остаются привязаны к выбранному региону.
Принятые Запросы хранятся ограниченное время, зависящее от тарифа и настроек. У каждого сохранённого Запроса есть собственная дата удаления. После истечения срока содержимое и история Доставки удаляются, поэтому Запрос больше нельзя просмотреть, повторить его Доставку или выполнить Replay.
Удаление Сервера останавливает новый приём и удаляет его Получателей. Уже принятые Запросы могут оставаться до запланированной даты удаления. Поддомен удалённого Сервера не используется повторно.
Adal не предназначен для постоянного хранения, резервного копирования или ведения архива. Сохраняйте нужные долгосрочные данные в собственных системах.
Безопасность и граница ответственности
Считайте чувствительными весь входящий Запрос и всю конфигурацию Получателя: URL, пути, параметры строки запроса, заголовки, тела, токены, ключи API и секреты подписи.
Adal шифрует чувствительные данные при хранении и использует защищённые соединения при передаче. Полное содержимое Запросов и конфигурацию доставки нельзя копировать в обычные журналы, трассировки, метрики, уведомления, отчёты об ошибках, сообщения поддержки или аналитические системы.
Adal делает приём и доставку вебхуков наблюдаемыми и управляемыми, но не заменяет проверки и устойчивость вашего приложения. Обработчик Получателя должен:
проверять подпись или другой способ аутентификации отправителя;
проверять формат и допустимые значения входных данных;
быть идемпотентным и безопасно обрабатывать повторную доставку;
удалять дубликаты по стабильному идентификатору события провайдера, если он доступен;
вести собственные журналы, мониторинг и обработку ошибок, не сохраняя чувствительные данные вебхуков без необходимости;
учитывать частичные сбои fan-out и повторные побочные эффекты.
Adal не является платёжным процессором, провайдером аутентификации, шлюзом безопасности или заменой очередей, баз данных, резервных копий, мониторинга и механизмов восстановления приложения.
Когда Adal подходит
Используйте Adal, когда нужна предсказуемая и прозрачная доставка вебхуков:
локальная разработка без публичного IP с Adal CLI;
просмотр реального payload провайдера до реализации обработчика;
перекрытие временной недоступности Получателя с хранением, повторами и Replay;
контролируемые автоматические и ручные повторы для неуспешных Доставок;
повторная отправка сохранённого Запроса без ожидания отправителя;
доставка одного Запроса нескольким Получателям (fan-out);
обработка в выбранном регионе и ограниченное хранение;
отладка незаметных сбоев доставки по истории Доставок.
Когда Adal не подходит
Не рассматривайте Adal как:
постоянное хранилище, резервную копию или архив;
систему доставки «ровно один раз»;
замену очередей, баз данных, журналов, мониторинга или восстановления приложения;
платёжный процессор;
провайдера аутентификации;
шлюз безопасности;
доказательство того, что Получатель завершил downstream-бизнес-операцию.
Успешная Доставка означает, что Adal получил ожидаемый HTTP-ответ от Получателя. Повторы и Replay могут создавать дубликаты; обработчики Получателей должны проверять подписи, валидировать входные данные, оставаться идемпотентными и удалять дубликаты, когда доступен стабильный идентификатор события провайдера.
Краткий словарь
| Понятие | Определение |
|---|---|
| Вебхук | HTTP-запрос, которым одна система сообщает другой о событии |
| Сервер (Server) | Публичная региональная точка приёма вебхуков в Adal |
| Запрос (Request) | Представление одного принятого HTTP-запроса в Adal |
| Получатель (Destination) | Настроенная цель, которая получает пересылаемые Запросы |
| Доставка (Delivery) | Процесс и история передачи одного Запроса одному Получателю |
| Попытка | Один фактический сетевой вызов в рамках Доставки |
| Повтор (Retry) | Новая попытка в рамках существующей Доставки |
| Replay | Новый Запрос, созданный из сохранённых данных более раннего Запроса |
| Регион | Место приёма, обработки и хранения данных Запроса |
| Срок хранения | Ограниченный период доступности Запроса и его истории |
Связанные страницы
Adal и похожие инструменты — определите, подходит ли Adal для вашего сценария.
Быстрый старт — создайте первый маршрут доставки и отправьте тестовый вебхук.
Серверы — изучите URL приёма, регионы, методы, ограничения и удаление.
Запросы — изучите содержимое, статусы и работу Replay.
Получатели — настройте Direct HTTP, Adal CLI и просматривайте историю Доставки.
Повторные попытки — изучите расписание, ручные действия, дубликаты и идемпотентность.
Хранение данных — изучите региональное хранение, сроки и удаление.
Безопасность — защитите данные, соединения и учётные данные.