Первый вебхук удобно проверить в RequestBin или Webhook.site. Вы получаете публичный URL, указываете его в настройках внешнего сервиса и видите входящий запрос: метод, заголовки, тело, иногда неожиданный формат данных. Для знакомства с интеграцией этого часто достаточно.
Затем появляется следующий шаг: передать запрос приложению. Локальному обработчику на ноутбуке, тестовому сервису или системе внутри закрытой production-сети. Теперь важно, что произойдёт, если приложение вернёт 500, соединение оборвётся или в момент события получатель вообще не будет подключён.
В этот момент меняются требования. Увидеть payment.succeeded в браузере полезно, но заказ от этого ещё не станет оплаченным. Нужны доставка, повторные попытки и возможность разобраться в результате.
Под рабочей, или production-like, интеграцией здесь мы понимаем поток, в котором запрос должен дойти до настоящего обработчика, а временные сбои и отключения получателя входят в обычный сценарий. Это может быть и разработка, и staging, и production.
Почему инспектор так удобен в начале
При первом подключении внешнего сервиса обычно неизвестно даже то, какой запрос он отправляет. Документация описывает общий формат, но в реальном событии появляются необязательные поля, дополнительные заголовки и особенности конкретного аккаунта.
Инспектор позволяет быстро ответить на несколько вопросов:
пришёл ли запрос от провайдера на указанный URL;
на какой путь пришёл запрос;
какие заголовки и тело он содержит;
чем тестовое событие отличается от ожидаемого формата.
Для этой задачи интерфейс со списком входящих запросов подходит хорошо. Не нужно сразу запускать приложение или разбираться с его логами.
Но запись в таком списке подтверждает только приём на публичной стороне. Пока запрос не дошёл до вашего обработчика, сама интеграция ещё не проверена.
Сравнивать стоит поведение при сбое
Название сервиса само по себе мало говорит о его возможностях. Например, Webhook.site поддерживает HTTP-пересылку и retries через Custom Actions, а также доставку через CLI. Поэтому утверждать, что у него вообще нет relay или повторных попыток, было бы неточно. Под названием RequestBin также встречаются разные сервисы и реализации.
Для выбора замены полезнее начать с текущего сценария. Если вы используете инструмент только как URL для приёма и просмотра запросов, переход к рабочей интеграции добавляет четыре требования:
| Задача | Что даёт приём и просмотр | Что требуется для рабочей доставки |
|---|---|---|
| Ошибка обработчика | Можно увидеть исходный запрос | Retry по заданным правилам и история попыток |
| Получатель в закрытой сети | Вебхук пришёл на публичный URL | Relay в заранее настроенный внутренний обработчик |
| Получатель отключён | Запрос может остаться в истории | Ожидание подключения и доставка сохранённого запроса |
| Несколько получателей | Доступен один входящий запрос | Явные Destinations и отдельный результат для каждой |
Это сравнение двух сценариев использования. Наличие нужной функции, её ограничения и поведение в конкретном тарифе стоит проверять по документации выбранного продукта.
Retry: что произойдёт после первой ошибки
Представим, что приложение перезапускается во время доставки вебхука. Запрос был принят на публичной стороне, но обработчик ещё не готов и возвращает 503.
Если дальше требуется вручную открыть запрос, скопировать тело и отправить его ещё раз, восстановление зависит от человека. Для единичного теста это допустимо. В постоянном потоке удобнее задать правила повторных попыток заранее.
В Adal Cloud retry относится к конкретной Delivery — доставке одного Request в одну Destination. При ответе вне диапазона 2xx, тайм-ауте или сетевой ошибке применяются настроенные правила повторных попыток. Успешная доставка одному получателю не отменяет retry для другого. Подробности — в документации по retries.
После исправления причины можно запустить ручной retry существующей доставки. Replay создаёт новый Request на основе сохранённого исходного запроса: это отдельная операция для повторного прогона. Их стоит различать и при отладке, и при оценке того, почему обработчик снова получил событие.
Повторная доставка требует идемпотентного обработчика. Если приложение выполнило действие, но ответ потерялся, следующая попытка может принести то же событие. Стабильный event ID провайдера помогает избежать второго заказа или уведомления. Мы разбирали это в статье «Почему вебхуки нужно обрабатывать идемпотентно».
Relay: как запрос попадёт в закрытую сеть
Публичному инспектору можно отправить вебхук из интернета. Внутреннему сервису на адресе 192.168.1.20 — напрямую нельзя. Для рабочей интеграции нужен ещё один участок маршрута.
В Adal Cloud внешний сервис отправляет запрос на постоянный HTTPS URL Сервера Adal Cloud. Для закрытого получателя Adal CLI запускается внутри его сети и устанавливает защищённое исходящее соединение:
Внешний сервис
→ публичный Сервер Adal Cloud
→ Request
→ Delivery
→ Adal CLI внутри закрытой сети
→ внутренний обработчик
Адрес обработчика задаёт владелец Destination. Внешнему отправителю достаточно публичного URL Сервера Adal Cloud; внутреннему сервису не нужны публичный IP и открытый входящий порт.
Если получатель уже доступен из интернета, можно использовать Destination типа Direct HTTP. Тогда Adal Cloud доставляет запрос напрямую, без CLI. Оба способа описаны в документации по Destinations.
Внутренний обработчик по-прежнему получает данные внешнего происхождения. Проверка подписи провайдера и прикладная валидация остаются частью интеграции.
Offline delivery: что будет, пока получатель отключён
Хранение запроса помогает увидеть, что пришло ночью. Для доставки утром нужна ещё связь между сохранённым запросом и ожидающим получателем.
В Adal Cloud приём и доставка разделены. Когда CLI отключён, Delivery ожидает соединения; попытка доставки в локальное приложение ещё не начинается и лимит попыток не расходуется. Когда CLI подключён, но само приложение недоступно или возвращает ошибку, это уже неуспешная попытка.
За автоматическую доставку ожидающих Requests после подключения отвечает настройка Сервера Deliver pending requests on connect. Она должна быть включена, нужный Request должен ещё храниться, Destination — существовать, а CLI — подключиться к нужному Серверу. Обработчик должен быть доступен по настроенному адресу. Поведение настройки описано в документации по Серверам Adal Cloud.
Для сценария «принять сейчас, изучить и доставить позже» настройте постоянное хранение с подходящим retention. Срок хранения ограничен: после удаления Request его нельзя восстановить или использовать для Replay. Условия постоянного и временного хранения различаются; они описаны в документации по хранению данных.
Такой сценарий полезен не только с выключенным ноутбуком. Он применим и при перезапуске CLI или временном обрыве соединения внутри закрытой сети.
Routing: куда должен попасть каждый запрос
Когда получатель один, маршрут кажется очевидным. Но один входящий вебхук может понадобиться основному приложению и отдельному сервису аудита. Тогда одной записи «запрос получен» становится мало.
В Adal Cloud к Серверу можно подключить несколько Destinations в пределах выбранного плана. Для каждого получателя создаётся отдельная Delivery со своей историей. В панели видно, какой маршрут завершился успешно, где произошла ошибка и какой получатель ещё ожидает подключения.
Например, основной обработчик вернул 200, а сервис аудита — 500. Успех первого маршрута не закрывает второй: retry применяется к неуспешной доставке. Команде не нужно повторно отправлять запрос всем получателям только ради одной ошибки.
Если потоки требуют разных наборов получателей, их можно разделить по Серверам Adal Cloud. Такое разделение делает назначение потока явным: события тестовой среды не должны случайно запускать действия в production.
Маршруты и данные принятого Request дают связанную картину: что пришло и как закончилась доставка в каждую цель. Успешный HTTP-ответ получателя остаётся транспортным результатом; завершение бизнес-операции проверяется в самом приложении.
Как проверить переход на практике
Для оценки нового маршрута достаточно одного тестового потока с настоящим обработчиком. Создайте Сервер Adal Cloud, включите постоянное хранение, настройте Destination и укажите публичный URL в тестовой среде провайдера.
Затем проверьте четыре ситуации:
Обычная доставка. Отправьте событие и сверьте Request в панели с тем, что получил обработчик.
Ошибка приложения. Временно верните
500и проверьте историю попыток и настроенный retry.Отключённый CLI. Включите
Deliver pending requests on connect, отключите CLI, отправьте событие и подключитесь снова в пределах retention.Частичный сбой. Добавьте второй тестовый получатель и проверьте, что ошибка одного маршрута видна отдельно от успеха другого.
Такой прогон покажет, подходит ли доставка вашему сценарию. Если обработчик требует специальный синхронный ответ для подтверждения webhook URL, это тоже нужно проверить заранее: ответ приёма на Сервере Adal Cloud настраивается отдельно от результата Delivery и не является ответом конечного приложения.
От первого запроса к постоянному маршруту
RequestBin и Webhook.site помогают быстро разобраться с форматом вебхука. Когда запрос должен запускать работу приложения, выбор инструмента начинает зависеть от поведения всей цепочки: при ошибке, отключении и доставке в несколько целей.
В Adal Cloud мы связываем публичный приём, хранение Request и управляемую доставку с историей попыток. Один и тот же принцип применим к локальной разработке и к обработчику в закрытой production-сети.
Начать можно с быстрого старта Adal Cloud, а затем проверить маршрут на тех сбоях, которые возможны именно в вашей интеграции.