Вебхук в n8n: настройка и почему он не срабатывает

«Вебхук не приходит» - самый частый вопрос по n8n. Хорошая новость: причин конечное число, и они проверяются по порядку за несколько минут.

Тестовый и боевой URL

Это источник большинства недоразумений, поэтому начнём с него.

Тестовый URL живёт, только пока вы нажали в редакторе кнопку прослушивания. Он ждёт один запрос, показывает пришедшие данные и замолкает. Инструмент отладки: удобно один раз посмотреть, что реально шлёт сервис.

Боевой URL работает постоянно, но только у активированного воркфлоу. Не активировали - адрес отвечает ошибкой.

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

Почему не приходит: порядок проверки

Идите сверху вниз, это быстрее, чем гадать.

1. Воркфлоу активирован? Причина номер один.
2. Тот ли URL? Тестовый вместо боевого - причина номер два.
3. n8n знает свой публичный адрес? Если переменная публичного адреса не задана, интерфейс покажет localhost, куда внешний сервис не достучится. См. установку.
4. HTTPS есть? Многие сервисы не отправляют вебхуки на http вовсе.
5. Метод совпадает? Нода ждёт POST, сервис шлёт GET - запрос не найдёт обработчик.
6. Путь совпадает? Лишний слэш в конце или изменённый путь в ноде дают 404.
7. Прокси не режет? Слишком строгий таймаут или лимит размера тела на реверс-прокси обрывает запрос до n8n.
8. Отправитель вообще шлёт? Посмотрите логи на его стороне: часто выясняется, что вебхук отключён или адрес сохранён неверно.

Самая полезная проверка: отправьте запрос обычным curl на боевой адрес. Если выполнение появилось в истории - n8n в порядке, проблема у отправителя. Если нет - дело в сети, адресе или активации.

Ответ вызывающей стороне

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

Иногда нужно вернуть результат работы - например, вы делаете API-эндпоинт. Тогда режим ответа переключается на возврат данных из указанной ноды, и появляется ограничение: вызывающая сторона ждёт. Если воркфлоу выполняется полминуты, отправитель полминуты держит соединение, и его собственный таймаут может сработать раньше вашего ответа.

Рабочее правило: длинная обработка - отвечайте сразу «принято», результат отдавайте отдельно колбэком, сообщением или записью в базу.

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

Защита эндпоинта

Вебхук - это открытый адрес в интернете, и его найдут: сканеры перебирают пути постоянно.

Минимальный набор:

• Секрет в запросе. Заголовок или токен, который проверяется первой же нодой. Не совпал - выполнение обрывается.
• Проверка подписи, если сервис её присылает. Надёжнее токена, потому что подтверждает и содержимое.
• Ничего не делать до проверки. Валидация стоит раньше любых действий с внешним миром.
• Ограничение размера тела на реверс-прокси.

И важное: длинный случайный путь не является защитой. Это не секрет, а просто адрес; он утечёт в логи, в историю браузера и в настройки сервиса, который его вызывает.

Дубли и повторы

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

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

Общая механика триггеров - триггеры и вебхуки. Разбор входящих данных - JSON в n8n. Обзор - гид по n8n.