Получатели Adal

Что такое получатель

Получатель (Destination) определяет, куда Adal доставляет запросы, принятые сервером.

Сервер принимает и сохраняет входящие вебхуки, а получатель задаёт адрес их дальнейшей доставки. Например:

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

Получателем может быть локальное приложение, подключённое через Adal CLI, или публичный HTTP URL. Если у сервера нет получателей, Adal продолжит принимать и сохранять запросы, но не будет автоматически доставлять их дальше.

Способы доставки

При создании получателя выберите способ, которым Adal будет доставлять запросы на указанный URL: напрямую по HTTP или через Adal CLI.

Direct HTTP

Adal отправляет запрос напрямую на публичный HTTP или HTTPS URL. Целевой сервис должен быть доступен из интернета и принимать входящие соединения из региона выбранного сервера.

Этот способ подходит для продакшен-сервисов, публичных API и серверов с собственным HTTPS.

Adal CLI

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

Этот способ подходит для локальной разработки, серверов за NAT и сервисов во внутренней сети.

Создание получателя

Откройте раздел получателей в панели управления , нажмите Добавить получателя и заполните форму.

1. Выберите регион.
2. Выберите сервер, запросы которого нужно доставлять.
3. Введите понятное название получателя.
4. Выберите способ доставки: Direct HTTP или Adal CLI.
5. Укажите целевой URL.
6. Выберите количество попыток доставки: от 1 до 10.
7. При необходимости добавьте примечание.
8. Нажмите Сохранить получателя.

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

Настройка доставки через Adal CLI

Выберите тип Adal CLI, если целевой сервис работает на локальном компьютере, за NAT или во внутренней сети и недоступен напрямую из интернета.

URL получателя

Укажите адрес сервиса, доступный с компьютера или сервера, на котором будет запущен CLI. Например:

URL не обязан быть публичным. Это может быть адрес в локальной или частной сети, если CLI может установить с ним соединение.

Подключение CLI

Запустите CLI с токеном сервера, выбранного при создании получателя:

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

Если CLI или локальный сервис недоступен

Если CLI не подключён, Adal не начинает попытку и не уменьшает их оставшееся количество. Доставка остаётся в статусе ожидания до следующего подключения CLI.

Если CLI подключён и получил запрос, но не смог обратиться к целевому URL, попытка считается неуспешной. Adal фиксирует её результат и применяет настройки повторной доставки получателя.

Поведение запросов, накопившихся во время отключения CLI, задаётся параметром сервера Доставлять ожидающие запросы при подключении. Если он включён, сохранённые ожидающие запросы будут переданы после следующего подключения. Если отключён, CLI будет получать только новые запросы.

Настройка Direct HTTP

Выберите тип Direct HTTP, если Adal должен обращаться к целевому сервису напрямую, без промежуточного CLI.

URL получателя

Укажите публичный адрес целевого сервиса. Например:

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

Передаваемый запрос

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

Например, если адрес получателя — https://example.com , а сервер принял запрос с URI /some/path?some=parameter , итоговый адрес доставки будет таким:

Вместе с исходным URI Adal передаёт:

• HTTP-метод;
• заголовки;
• тело запроса.

Таким образом, настройка получателя определяет схему, хост и порт целевого сервиса, а URI берётся из принятого запроса без изменений.

Проверка доступности

Перед сохранением убедитесь, что URL отвечает на ожидаемый HTTP-метод и не требует доступа из локальной или частной сети. Для закрытых сервисов используйте доставку через Adal CLI.

Если соединение не установлено или сервис возвращает ошибку, Adal фиксирует неуспешную попытку и применяет настройки повторной доставки получателя.

Связь получателей с серверами

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

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

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

Доставки выполняются и отслеживаются независимо. Ошибка одного получателя не блокирует отправку другим: один и тот же запрос может быть успешно доставлен в продакшен и завершиться ошибкой при отправке в систему аудита.

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

Как выполняется доставка

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

1. Adal определяет получателей, настроенных для сервера.
2. Для каждого получателя создаётся отдельная попытка доставки.
3. Adal выбирает настроенный способ доставки: Direct HTTP или Adal CLI.
4. Запрос отправляется на адрес получателя с исходными HTTP-методом, URI, заголовками и телом.
5. Adal фиксирует результат попытки: ответ получателя либо возникшую ошибку.
6. Если требуется повтор, следующая попытка планируется согласно настройкам получателя.

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

Ответ целевого сервиса означает, что HTTP-запрос дошёл до получателя. Он не подтверждает, что сервис полностью обработал вебхук, записал данные или успешно выполнил бизнес-операцию — это контролирует само целевое приложение.

Результаты доставки и повторные попытки

Успешная доставка

Доставка считается успешной, если получатель вернул любой HTTP-статус из диапазона 2xx . После этого Adal не планирует для неё автоматические повторные попытки.

Статус 2xx подтверждает получение запроса целевым сервисом, но не гарантирует успешное завершение его внутренней обработки.

Неуспешная доставка

Попытка считается неуспешной, если получатель вернул статус вне диапазона 2xx либо запрос не удалось завершить. Например:

• не удалось установить сетевое соединение;
• истёк тайм-аут;
• произошла ошибка DNS или TLS;
• получатель вернул статус 4xx или 5xx ;
• CLI не может обратиться к локальному сервису.

Отключённый Adal CLI не считается ошибкой попытки. Пока CLI не подключён, доставка остаётся в ожидании, а неиспользованные попытки сохраняются.

Автоматические повторные попытки

Для каждого получателя можно выбрать от 1 до 10 попыток. Значение относится только к этому получателю и включает первую попытку доставки. Если выбрана одна попытка, автоматических повторов не будет.

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

Здесь n — номер следующей попытки. Поэтому попытка №2 выполняется через 4 минуты после завершения первой, попытка №3 — через 9 минут после завершения второй, попытка №4 — через 16 минут после завершения третьей и так далее.

Если во время ожидания CLI отключился, запланированная попытка не расходуется. После подключения она выполняется сразу, если рассчитанное время уже наступило. Отсчёт для следующей попытки начинается только после завершения текущей.

Например, после третьей попытки Adal CLI отключился на час. После подключения попытка №4 выполнится сразу, поскольку её 16-минутная задержка уже прошла. Если она завершится ошибкой, попытка №5 будет выполнена через 25 минут после завершения попытки №4.

Повторы прекращаются после успешного ответа 2xx или после исчерпания выбранного количества попыток. Автоматические повторы относятся к исходному запросу и не расходуют дополнительные кредиты.

История доставки

История доставки помогает проследить путь принятого запроса до каждого получателя. Откройте запрос в панели управления, чтобы увидеть связанные с ним попытки доставки.

Для каждой попытки Adal показывает технические сведения о результате, в том числе:

• получателя и способ доставки;
• номер попытки;
• дату и время выполнения;
• текущий статус;
• HTTP-статус ответа, если он был получен;
• время выполнения запроса;
• сообщение о сетевой, DNS-, TLS- или другой ошибке.

Попытки сгруппированы по получателям. Поэтому для одного входящего запроса можно отдельно увидеть, что доставка получателю A завершилась успешно, получателю B ожидает подключения CLI, а для получателя C запланирован автоматический повтор.

Статус ожидания означает, что попытка ещё не началась. Например, доставка через Adal CLI остаётся в ожидании, пока CLI не подключён; такая запись не расходует доступное количество попыток.

История попыток хранится вместе с запросом и подчиняется сроку хранения, настроенному для его сервера.

Ручной повтор, отмена и повторная отправка

Ручной повтор доставки

Ручной повтор заново запускает доставку существующего запроса конкретному получателю. Он не затрагивает доставки этого запроса другим получателям.

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

Каждый ручной повтор является отдельной операцией и расходует 1 кредит. Автоматические повторы, напротив, входят в обработку исходного запроса и дополнительных кредитов не расходуют.

Отмена ожидающей доставки

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

Отмена не отзывает запрос, который уже был отправлен, и не влияет на доставки другим получателям. Если запрос всё же нужно отправить отменённому получателю, запустите доставку вручную.

Повторная отправка запроса

Повторная отправка (Replay) заново проводит сохранённый запрос через процесс сервера. Adal создаёт новый запрос на основе исходного и запускает обычную доставку всем получателям, настроенным для сервера на момент повторной отправки.

Исходный запрос не изменяется. В отличие от ручного повтора доставки одному получателю, Replay создаёт новый запрос и новые доставки. Операция расходует 1 кредит.

Idempotency key

Idempotency key помогает целевому сервису распознавать повторные доставки одного и того же запроса и не выполнять одну бизнес-операцию несколько раз.

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

Ключ создаётся на уровне запроса, а не отдельной доставки. Поэтому один запрос получает одинаковое значение X-Adal-Idempotency во всех получателях, для которых включена эта настройка.

Чтобы использовать ключ, целевой сервис должен сохранять уже обработанные значения заголовка и не повторять действие при получении известного значения.

Безопасность получателей

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

Используйте HTTPS для Direct HTTP

Для публичных получателей используйте HTTPS с действительным TLS-сертификатом. Это защищает URI, заголовки и тело вебхука при передаче от Adal до целевого сервиса.

Защищайте токен Adal CLI

Токен связывает CLI с сервером. Не добавляйте его в репозиторий, журналы приложения, снимки экрана или общедоступные команды. Запускайте CLI только в доверенной среде и ограничивайте доступ к процессу и его конфигурации.

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

Проверяйте вебхуки в целевом приложении

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

Используйте X-Adal-Idempotency , если для получателя включена передача ключа, чтобы повторная доставка не вызвала повторное выполнение чувствительной операции.

Хранение конфигурации и данных

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

Данные запросов и история доставки удаляются согласно сроку хранения сервера. Adal не хранит заголовки и тела ответов, возвращённых получателем.

Ограничения и особенности

Тайм-ауты доставки

Adal ожидает установления соединения с получателем не более 5 секунд. Полный тайм-аут одной попытки, включая соединение, передачу запроса и получение ответа, составляет 30 секунд.

Если соответствующий тайм-аут истёк, попытка завершается ошибкой и участвует в обычном процессе автоматических повторов.

Адрес Direct HTTP

Direct HTTP поддерживает адреса с HTTP и HTTPS, в том числе с нестандартными портами и перенаправлениями. Для HTTPS минимальная поддерживаемая версия протокола — TLS 1.2.

В Direct HTTP нельзя указывать локальные адреса. Это ограничение не позволяет серверу Adal отправлять запросы самому себе. Для доставки на localhost , loopback-адреса или сервисы в частной сети используйте Adal CLI.

Ограничения тарифа и хранения

Максимальное число получателей у одного сервера и допустимый размер входящего запроса зависят от тарифа. Для каждого получателя можно настроить от 1 до 10 попыток доставки.

История попыток хранится вместе с запросом до окончания срока хранения его сервера. Заголовки и тела ответов получателя не сохраняются.

Удаление получателя

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

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

Устранение неполадок

Запрос принят, но получатель его не получил

Откройте запрос в панели управления и проверьте историю доставки нужному получателю. Убедитесь, что получатель относится к правильному серверу, а его адрес и способ доставки указаны верно.

Если попыток нет, доставка может ожидать подключения Adal CLI. Если попытка уже выполнялась, проверьте её HTTP-статус или сообщение об ошибке.

Adal CLI отображается как отключённый

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

Пока CLI отключён, доставка остаётся в ожидании и не расходует попытки. После подключения просроченная по расписанию попытка выполняется сразу.

Локальный сервис недоступен для CLI

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

Получатель возвращает 404

Adal пересылает точную копию URI входящего запроса. Если сервер принял /some/path?some=parameter , целевой сервис должен обрабатывать этот же путь и параметры. Проверьте маршруты приложения и не добавляйте путь к адресу получателя.

Получатель возвращает 401 или 403

Целевой сервис отклонил запрос на уровне аутентификации или авторизации. Проверьте ожидаемые им заголовки, токены, подпись вебхука и права доступа.

Получатель возвращает 429 или 5xx

Такой ответ считается неуспешной попыткой. Adal повторит доставку по расписанию, пока не получит ответ 2xx или не исчерпает настроенное количество попыток. Проверьте ограничения частоты и журналы целевого сервиса.

Ошибка соединения, DNS, TLS или тайм-аута

• проверьте DNS-запись и доступность хоста из интернета;
• убедитесь, что порт открыт и сервис принимает соединения;
• для HTTPS проверьте сертификат и поддержку TLS 1.2 или новее;
• учитывайте лимит 5 секунд на соединение и 30 секунд на всю попытку;
• для локального адреса используйте Adal CLI вместо Direct HTTP.

Один запрос пришёл несколько раз

Повтор возможен после ошибки, тайм-аута или потери ответа: получатель мог обработать запрос, даже если Adal не получил успешный статус. Включите передачу X-Adal-Idempotency и устраняйте дубли в целевом приложении по значению этого заголовка.

Запрос доставлен одному получателю, но не доставлен другому

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

Связанные страницы

• Быстрый старт — создание сервера, получателя и первая тестовая доставка.
• Серверы — приём запросов, регионы, ограничения и настройки сервера.
• Хранение данных и сроки хранения — какие данные запросов и доставок хранит Adal и когда они удаляются.
• Безопасность — шифрование, доступ к данным и рекомендации по защите конфигурации.