Серверы Adal

Что такое сервер?

Сервер — это публичный URL в Adal, принимающий запросы вебхуков от внешних сервисов.

Когда GitHub, Stripe, Slack, Telegram, Make, Zapier или другому сервису нужно отправить событие вашему приложению, укажите URL сервера Adal как адрес вебхука. Adal примет запрос, сохранит его сведения и отобразит в панели управления.

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

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

В упрощённом виде:

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

Когда использовать серверы

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

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

Распространённые сценарии:

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

Например, URL сервера Adal можно указать для вебхуков GitHub, Stripe, Slack, Telegram, Make, Zapier или другого сервиса. Adal запишет запрос и покажет полученные данные без изменений.

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

Создание сервера

Откройте раздел серверов в панели Adal, нажмите Создать сервер и настройте приём входящих вебхуков.

Регион

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

Регион становится частью URL. Например, для региона se1 URL выглядит так:

Выберите регион, подходящий для вашей инфраструктуры и сервисов — отправителей вебхуков.

Название

Введите название сервера.

Название используется только в панели Adal и не влияет на URL, обработку, доставку и интеграции.

Выберите понятное назначение, например:

• GitHub — разработка
• Stripe — продакшен
• Telegram-бот

Разрешённые методы

Выберите HTTP-методы, которые должен принимать сервер.

Adal поддерживает следующие методы:

• DELETE
• GET
• HEAD
• OPTIONS
• PATCH
• POST
• PUT

Запросы с неразрешённым методом отклоняются сразу при поступлении.

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

Доставлять ожидающие запросы при подключении

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

Доступные варианты:

• Включено
• Отключено

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

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

Примечания

Поле «Примечания» предназначено для внутренних заметок о сервере.

Примечания не влияют на обработку, доставку и внешние интеграции.

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

URL сервера

У каждого сервера есть публичный URL для отправки вебхуков в Adal.

Скопируйте URL в панели Adal и укажите его как адрес вебхука в GitHub, Stripe, Slack, Telegram, Make, Zapier или любом другом сервисе, поддерживающем HTTP-вебхуки.

Например:

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

Регион является частью URL. В примере se1 обозначает регион приёма запросов:

Для сервера в другом регионе эта часть URL будет отличаться.

На том же сервере можно использовать произвольный путь:

Параметры запроса также поддерживаются:

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

Не удаляйте сервер, пока его URL настроен во внешних сервисах. После удаления приём запросов прекратится.

В целях безопасности поддомены удалённых серверов не освобождаются и не используются повторно.

Регионы

Каждый сервер относится к определённому региону.

Регион определяет, где Adal принимает и обрабатывает вебхуки. Он выбирается при создании сервера.

Выбранный регион становится частью URL. Например, сервер в регионе se1 получит такой URL:

В другом регионе соответствующая часть URL изменится:

Выбирайте регион ближе к инфраструктуре, пользователям или сервисам — отправителям вебхуков.

Позже изменить регион нельзя. Создайте новый сервер в нужном регионе и обновите URL во внешнем сервисе.

Запросы, доставки и URL привязаны к региону, поэтому маршрутизация остаётся явной и предсказуемой.

Входящие запросы

Когда внешний сервис отправляет вебхук на URL сервера, Adal принимает его как входящий HTTP-запрос.

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

Для принятых запросов Adal сохраняет:

• HTTP-метод;
• путь;
• параметры запроса;
• заголовки;
• тело;
• размер запроса;
• IP-адрес источника;
• время получения;
• статус доставки.

Например, если внешний сервис отправляет запрос на адрес:

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

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

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

Пути и параметры запроса

Сервер принимает запросы как на корневой URL, так и на произвольные пути под ним.

Все следующие адреса могут относиться к одному серверу:

• https://a1b2.se1.adal.cloud
• https://a1b2.se1.adal.cloud/github/push
• https://a1b2.se1.adal.cloud/stripe/events
• https://a1b2.se1.adal.cloud/telegram/bot

Параметры запроса также поддерживаются:

Adal сохраняет путь и параметры вместе с запросом для просмотра в панели.

Это удобно для сервисов с определённым путём или нескольких связанных источников на одном сервере.

Например, можно использовать разные пути:

• https://a1b2.se1.adal.cloud/github/push
• https://a1b2.se1.adal.cloud/github/issues
• https://a1b2.se1.adal.cloud/github/releases

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

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

Ограничения запросов

Серверы принимают запросы с учётом ограничений текущего тарифа и настроек сервера.

Главное ограничение — максимальный размер запроса. В Adal он складывается из URI, заголовков и тела:

Если запрос превышает лимит тарифа, Adal отклоняет его при поступлении.

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

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

Запрос также отклоняется при несоответствии настройкам. Например, если разрешён только POST , входящий GET будет сразу отклонён.

Основные причины отказа:

• размер превышает лимит тарифа;
• HTTP-метод не разрешён в настройках;
• сервер больше не существует;
• регион не может принять запрос.

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

Ограничения защищают инфраструктуру, обеспечивают предсказуемую обработку и понятные причины отказа.

Кредиты

Кредиты учитывают принятые запросы и ручные операции: повторную отправку запроса или доставки.

Один принятый входящий запрос расходует 1 кредит.

Этот кредит покрывает весь стандартный процесс:

За принятый вебхук списывается 1 кредит: за приём, хранение и автоматическую доставку всем получателям.

Автоматические повторные попытки включены и не расходуют дополнительные кредиты.

Отклонённые запросы не расходуют кредиты: они не считаются принятыми и не тарифицируются.

Дополнительные кредиты расходуют новые операции обработки:

• повторная отправка запроса — 1 кредит;
• ручной повтор доставки — 1 кредит.

При нехватке кредитов новые запросы не принимаются, пока баланс не будет пополнен.

Запросы сервера

Один сервер может принимать множество запросов.

Каждый принятый HTTP-запрос сохраняется отдельно и представляет одно конкретное событие вебхука.

Если GitHub отправит три события на один сервер, Adal сохранит три отдельных запроса:

Каждый запрос можно открыть и посмотреть полученные данные и дальнейшую обработку.

Доступные сведения:

• HTTP-метод
• URI
• Путь
• Параметры запроса
• Заголовки
• Тело
• Размер
• IP-адрес источника
• Время получения
• Статус и попытки доставки

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

При наличии получателей запрос содержит попытки доставки в приложение, CLI или HTTP-получателю.

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

Причина отказа указана на странице запроса.

Получатели

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

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

Например:

У сервера может быть один или несколько получателей в пределах тарифа.

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

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

Adal записывает результат доставки: успех, ошибку или ожидание следующей попытки.

Получатели настраиваются отдельно: сервер управляет приёмом, а получатели — местом доставки.

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

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

Основной процесс:

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

Например:

Попытка показывает, была ли доставка успешной, завершилась ошибкой, ожидает выполнения или повтора.

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

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

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

Ручной повтор конкретной доставки является отдельной операцией и расходует дополнительный кредит.

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

Повторная отправка позволяет заново провести ранее полученный запрос через процесс сервера.

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

Adal создаёт новый запрос на основе исходного и запускает обычный процесс:

Исходный запрос не изменяется, а новый сохраняется отдельно.

Функция доступна, пока необходимые исходные данные ещё хранятся.

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

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

Повторная отправка создаёт новый запрос, а ручной повтор заново выполняет конкретную существующую доставку.

Рекомендации по безопасности

URL-адреса серверов являются публичными.

Любой знающий URL может отправить на него HTTP-запрос в пределах настроек и ограничений тарифа.

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

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

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

Разрешайте только ожидаемые HTTP-методы. Запросы с отключёнными методами будут отклонены на входе.

В целях безопасности поддомены удалённых серверов не освобождаются и не выдаются другим аккаунтам.

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

Удаление сервера

Ненужный сервер можно удалить в панели Adal.

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

Внешние сервисы с прежним URL больше не смогут доставлять запросы в Adal.

Удаление затрагивает весь связанный процесс:

После удаления URL становится неактивным и новые запросы не принимаются.

Поддомены удалённых серверов не освобождаются и не используются повторно.

Удаление не равно временному отключению. Чтобы остановить доставку, сохранив URL, отключите или удалите получателей.

Удаляйте сервер только после обновления или удаления его URL во всех внешних сервисах.

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

Здесь перечислены распространённые проблемы при работе с серверами.

Вебхук отправлен, но не отображается в Adal

Проверьте URL сервера во внешнем сервисе.

Убедитесь, что URL содержит правильный регион и поддомен:

Также проверьте:

• сервер существует;
• запрос отправляется на правильный URL;
• метод разрешён;
• размер не превышает лимит;
• кредитов достаточно;
• регион доступен.

Отклонённый на входе запрос появится со статусом rejected , и для него сохранятся только минимальные метаданные.

Запрос отклонён

Запрос может быть отклонён до начала обычной обработки.

Основные причины:

• HTTP-метод не разрешён;
• размер превышает лимит;
• сервер удалён;
• недостаточно кредитов;
• регион не может принять запрос.

Размер запроса рассчитывается так:

Поэтому лимит может быть превышен из-за больших заголовков или длинного URI даже при небольшом теле.

Запрос существует, но не доставлен

Если запрос виден, проверьте настроенных получателей.

Возможные причины:

• получатели не настроены;
• получатель отключён или настроен неверно;
• целевое приложение или HTTP URL недоступны;
• Adal CLI не подключён;
• цель вернула ошибку;
• доставка ожидает выполнения или повтора.

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

Ожидающие запросы не доставляются при подключении CLI

Проверьте настройку Доставлять ожидающие запросы при подключении.

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

Если она отключена, пересылаются только новые запросы.

Внешний сервис сообщает об ошибке доставки вебхука

Откройте соответствующий запрос в Adal и проверьте статус доставки.

Если запроса нет, проверьте URL, разрешённые методы, размер, кредиты и доступность региона.

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

Нужно остановить доставку, сохранив URL сервера

Не удаляйте сервер.

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

Чтобы сохранить URL, удалите или отключите получателей.

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

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

• Запросы
• Получатели
• Adal CLI