Получатели Adal

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

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

Server принимает входящие вебхуки, а Destination задаёт адрес их дальнейшей Delivery. Будет ли Request постоянно сохранён или только временно останется в памяти, зависит от режима хранения Server:

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

Destination может быть локальным приложением, подключённым через Adal CLI, или публичным HTTP URL. Если у Server нет Destinations, постоянное хранение позволяет сохранять Requests для просмотра. В режиме временной доставки отсутствие Destinations означает, что работы Delivery нет, поэтому принятый Request удаляется из памяти сразу после обработки приёма.

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

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

Direct HTTP

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

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

Adal CLI

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

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

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

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

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

1. Выберите регион.

2. Выберите сервер, запросы которого нужно доставлять.

3. Введите понятное название получателя.

4. Выберите способ доставки: Direct HTTP или Adal CLI.

5. Укажите целевой URL.

6. Выберите количество попыток доставки: от 1 до 10.

7. При необходимости добавьте примечание.

8. Нажмите Сохранить получателя.

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

Важно: Название и примечание нужны только для работы в панели управления. Они не добавляются в HTTP-запрос и не передаются целевому сервису.

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

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

URL получателя

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

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

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

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

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

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

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

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

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

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

Настройка 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 фиксирует неуспешную попытку и применяет настройки повторной доставки получателя.

Важно: Direct HTTP не требует запущенного Adal CLI. Запрос отправляется из инфраструктуры Adal непосредственно на URL получателя.

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

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

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

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

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

Если для Server не настроено ни одного Destination, постоянное хранение позволяет сохранять принятые Requests для просмотра, но Server не пересылает их автоматически. Временный Request удаляется из памяти сразу после обработки приёма, поскольку работы ни с одним Destination нет.

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

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

Delivery начинается после того, как Server принял Request. Дальнейшая работа с каждым Destination выполняется отдельно, а данные остаются доступными согласно выбранному режиму хранения.

1. Adal определяет получателей, настроенных для сервера.

2. Для каждого получателя создаётся отдельная попытка доставки.

3. Adal выбирает настроенный способ доставки: Direct HTTP или Adal CLI.

4. Запрос отправляется на адрес получателя с исходными HTTP-методом, URI, заголовками и телом.

5. Adal фиксирует результат попытки: ответ получателя либо возникшую ошибку.

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

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

В режиме временной доставки полный Request остаётся в памяти Redis, пока работа хотя бы с одним Destination не завершена. Успешный Delivery в Destination A не удаляет данные, необходимые для ожидающего повтора в Destination B. Adal удаляет Request после успеха или исчерпания попыток во всех Destinations либо раньше при истечении временного retention.

Ответ целевого сервиса означает, что 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 или после исчерпания выбранного количества попыток. Автоматические повторы относятся к исходному запросу и не расходуют дополнительные кредиты.

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

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

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

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

• получателя и способ доставки;

• номер попытки;

• дату и время выполнения;

• текущий статус;

• HTTP-статус ответа, если он был получен;

• время выполнения запроса;

• сообщение о сетевой, DNS-, TLS- или другой ошибке.

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

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

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

При постоянном хранении история попыток сохраняется вместе с Request и подчиняется retention его Server. При временной доставке состояние попыток существует только в памяти Redis, пока работа Delivery активна, и удаляется вместе с Request.

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

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

Ручной повтор заново запускает Delivery постоянно сохранённого Request в конкретный Destination. Он не затрагивает Deliveries этого Request в другие Destinations.

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

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

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

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

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

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

Replay заново проводит постоянно сохранённый Request через процесс Server. Adal создаёт новый Request на основе исходного и запускает обычную Delivery во все Destinations, настроенные для Server на этот момент. После завершения in-memory жизненного цикла временный Request нельзя использовать для Replay.

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

Idempotency key

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

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

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

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

Важно: Idempotency key не гарантирует доставку ровно один раз. Adal может отправить запрос повторно, а защиту от повторной обработки реализует целевой сервис.

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

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

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

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

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

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

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

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

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

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

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

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

Постоянно сохранённые данные Request и история Delivery удаляются по окончании retention или раньше при удалении Server. Временный Request остаётся в памяти, пока хотя бы для одного Destination работа не завершена, и удаляется после успеха или исчерпания попыток во всех Destinations либо раньше при истечении временного retention. Adal не хранит заголовки и тела ответов, возвращённых Destination.

Важно: Вы отвечаете за безопасность указанного URL и за дальнейшую обработку данных после их доставки получателю.

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

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

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

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

Адрес Direct HTTP

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

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

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

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

Постоянная история попыток хранится вместе с Request до окончания retention или удаления Server. Временное состояние попыток удаляется вместе с in-memory Request по окончании его более короткого жизненного цикла. Заголовки и тела ответов Destination не сохраняются.

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

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

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

Важно: Удаление получателя нельзя отменить. Если нужно временно остановить ожидающую доставку, отмените её вместо удаления получателя.

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

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

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

Если попыток нет, доставка может ожидать подключения 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 и устраняйте дубли в целевом приложении по значению этого заголовка.

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

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

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

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

• Быстрый старт — создание сервера, получателя и первая тестовая доставка.

• Серверы — приём запросов, регионы, ограничения и настройки сервера.

• Хранение данных и сроки хранения — какие данные запросов и доставок хранит Adal и когда они удаляются.

• Безопасность — шифрование, доступ к данным и рекомендации по защите конфигурации.

• Почему вебхуки нужно обрабатывать идемпотентно — почему возникают повторные доставки и как использовать X-Adal-Idempotency.