Webhook n8n: HTTPS, аутентификация и доставка

Укажите отправителю настоящий production URL

Webhook позволяет другому сервису запустить workflow HTTP-запросом. До регистрации адреса завершите установку HTTPS. Test URL и production URL в редакторе работают по-разному: тестовый listener включён на время проверки, а production требует опубликованного сценария. Копируйте нужный URL из Webhook-ноды, не собирайте его по памяти.

В комплекте заданы WEBHOOK_URL=https://your-domain/, HTTPS-адрес редактора и N8N_PROXY_HOPS=1 для единственного Caddy proxy. БД и task broker доступны внутри Docker, прямой порт редактора — только через loopback. При добавлении CDN или второго proxy заново проверьте число доверенных proxy и forwarded headers; не увеличивайте значение наугад.

Сначала соберите безвредный приёмник

Создайте workflow с POST Webhook и Respond to Webhook. В первой ноде выберите ответ через вторую. В Authentication выберите Header Auth и создайте credential со случайным значением приватного заголовка, например X-Workflow-Key. Верните фиксированный JSON {"accepted":true} без платных запросов и записи данных.

Проверьте test URL при включённом listener. Затем сохраните и опубликуйте workflow, проверьте production URL. Нужны четыре случая: правильный заголовок, отсутствующий, неверный и некорректное тело запроса. Аутентификация по заголовку не проверяет бизнес-поля JSON. Перед внешними действиями добавьте проверки обязательных полей, типов и длины.

Если провайдер подписывает тело webhook, проверяйте подпись по его спецификации. Пример с общим секретным заголовком такую проверку не заменяет. Не считайте трудноугадываемый путь достаточной аутентификацией.

Учитывайте дубликаты и timeout

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

Для платного inference timeout не доказывает, что токены не были потрачены. Ручной AI-пример отключает автоматические повторы ноды, но это не устраняет дубликаты отдельных webhook-событий. Комплект не гарантирует выполнение ровно один раз.

Ограничьте входящие HTTP-запросы

Caddy ограничивает тело запроса одним мегабайтом. Для больших файлов нужен продуманный путь через файловое хранилище, а не бесконтрольное увеличение лимита всех endpoint. Не передавайте токены в query string: их могут сохранить proxy и журналы запросов. Данные ошибочного выполнения также могут содержать входной payload.

404 часто означает неправильный test/production URL, неопубликованный workflow или выключенный тестовый listener. 502 обычно говорит, что proxy не соединяется с n8n. Ошибка TLS возникает ещё до запуска сценария. Проверяйте эти уровни последовательно по инструкции устранения ошибок.

Все руководства по n8n.

Официальные источники: Reverse proxy configuration.