Beta

Webhook-коннектор: приём внешних событий во внутренний сервис

Назначение, безопасные сценарии и пошаговая настройка передачи webhook-событий в один заранее заданный внутренний адрес.

Шаги

Выполняйте по порядку.

01Понять границу доступаВнешний сервис обращается к BusinessProxy; коннектор из вашей сети сам подключается к одному заранее заданному внутреннему адресу.
02Выбрать безопасный сценарийПлатёжные уведомления, события репозиториев и события от партнёрских систем подходят, если внутренний адрес заранее задан.
03Войти в CLI управленияПодтвердите вход в браузере; не переносите пользовательские токены в заметки оператора.
04Создать коннектор и рабочий секретСоздайте webhook-коннектор, скопируйте одноразовый рабочий токен и сохраните его как секрет.
05Создать точку приёмаСвяжите публичный адрес с одним внутренним адресом, списком методов, лимитом размера тела, таймаутом и ограничением частоты.
06Запустить, проверить и наблюдатьЗагрузите переменные окружения, выполните проверки, запустите процесс и отправьте smoke-запрос без раскрытия секретов.
07Обновить или отозвать секретыТокен коннектора и секрет точки приёма меняются отдельно; чтобы остановить приём, отзовите секрет или отключите точку приёма.

Справочник

Детали реализации для настройки и проверки.

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

Отправитель не может выбрать внутренний адрес назначения.
Рабочий токен webhook-коннектора отделён от токенов коннектора доступа к внутренним приложениям.
Тела запросов и ответов не записываются в журналы коннектора.

Подходящие сценарииИспользуйте webhook-коннектор, когда один известный внешний сервис передаёт событие одному внутреннему обработчику, а обработчик всё равно проверяет событие способом, принятым у провайдера. Не превращайте его в публичный прокси к произвольным внутренним адресам.

Платежи: платёжный провайдер отправляет событие в BusinessProxy, а внутренний биллинг затем проверяет номер платежа, сумму и валюту через API провайдера.
Репозитории: сервис контроля версий сообщает внутреннему сервису сборки о новом теге или merge request.
Партнёрские системы: система клиента или поставщика передаёт событие о состоянии заказа одному внутреннему интеграционному обработчику.
Внутренние инструменты: сервис форм отправляет подписанное событие во внутренний helpdesk или CRM-сервис приёма заявок.

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

В обычных средах используйте HTTPS для API BusinessProxy.
Храните рабочие токены и секреты точек приёма в защищённом хранилище, а не в обращениях в поддержку или на снимках экрана.
Для платёжных событий не доверяйте одному только телу запроса; перед выдачей услуги подтвердите платёж у провайдера.

Войти для управленияCLI-команда открывает страницу подтверждения в браузере и сохраняет локальные учётные данные с ограниченной областью действия. Для автоматизации можно передать заранее выданный пользовательский токен через BUSINESSPROXY_ACCESS_TOKEN, но для оператора обычный путь — подтверждение в браузере.

export BUSINESSPROXY_API_URL=https://api.business-proxy.com

webhook-connector auth login --api-url "$BUSINESSPROXY_API_URL"
webhook-connector auth status

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

webhook-connector connector create \
  --workspace-id <идентификатор-рабочей-области> \
  --name "уведомления о платежах" \
  --json

webhook-connector config env-template \
  --workspace-id <идентификатор-рабочей-области> \
  --connector-id <идентификатор-коннектора> \
  --token <одноразовый-рабочий-токен> \
  > .env.webhook-connector

Создать точку приёмаТочка приёма связывает один публичный адрес BusinessProxy с одним заранее заданным внутренним адресом. Начните только с метода POST, задайте лимит размера тела, таймаут и ограничение частоты, затем передайте возвращённый callback URL внешнему сервису.

webhook-connector endpoint create \
  --workspace-id <идентификатор-рабочей-области> \
  --connector-id <идентификатор-коннектора> \
  --name "приём платёжных webhook-событий" \
  --provider custom \
  --auth-mode header \
  --token-header-name X-Webhook-Token \
  --upstream http://10.0.0.10:13000/payment/provider/notification \
  --method POST \
  --max-body 1048576 \
  --timeout 30 \
  --rate-limit 60 \
  --json

Запустить и проверитьЗагрузите созданный файл переменных на хосте коннектора, выполните локальные проверки и запустите процесс. Когда процесс перейдёт в рабочее состояние, отправьте smoke-запрос на публичный адрес. В выводе smoke-проверки секрет адреса скрывается.

set -a
. ./.env.webhook-connector
set +a

webhook-connector config check
webhook-connector doctor
webhook-connector run

webhook-connector smoke \
  --callback-url "https://wh-example.business-proxy.com/custom/<секрет-точки-приёма>" \
  --secret <секрет-точки-приёма> \
  --body '{}'

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

webhook-connector connector rotate-token \
  --workspace-id <идентификатор-рабочей-области> \
  --connector-id <идентификатор-коннектора>

webhook-connector endpoint rotate-secret \
  --workspace-id <идентификатор-рабочей-области> \
  --endpoint-id <идентификатор-точки-приёма>

webhook-connector endpoint revoke-secret \
  --workspace-id <идентификатор-рабочей-области> \
  --endpoint-id <идентификатор-точки-приёма>

webhook-connector endpoint disable \
  --workspace-id <идентификатор-рабочей-области> \
  --endpoint-id <идентификатор-точки-приёма>

Что проверить при ошибкеЧаще всего ошибки связаны с неверным API URL, истёкшими учётными данными управления, сменой рабочего токена, недоступным внутренним адресом, проблемой доверия к TLS-сертификату, ограничением метода, размера тела или частоты либо SSRF-защитой.

Ошибка HTTPS: используйте HTTPS; только для местной разработки с локальным адресом 127.0.0.1 или localhost задайте BUSINESSPROXY_DEVELOPMENT_ALLOW_HTTP_API=true для команд управления и WEBHOOK_CONNECTOR_DEVELOPMENT_ALLOW_HTTP_API=true для рабочего процесса.
Ошибка авторизации CLI: выполните auth status, затем auth logout и auth login, если сохранённые учётные данные истекли или относятся к другой рабочей области.
Рабочий процесс не прошёл проверку: обновите WEBHOOK_CONNECTOR_TOKEN после смены токена и перезапустите коннектор.
Таймаут внутреннего сервиса: проверьте, что хост коннектора видит внутренний адрес по DNS, TCP и TLS.
Сработала SSRF-защита: оставьте точку приёма привязанной к заранее заданному адресу; не передавайте адрес назначения из входящего запроса.