Надёжный приём вебхука в n8n держится на трёх вещах: проверке отправителя, защите от повторной доставки и журнале ошибок. Узел Webhook принимает запрос, а всё остальное сценарий должен сделать сам, потому что внешние сервисы присылают одно событие дважды, шлют его с задержкой и иногда ломают формат. Для событий, которые меняют деньги или заявки клиентов, без этих мер включать сценарий рано.
Приём события
Узел Webhook создаёт два адреса: тестовый показывает входящие данные в редакторе, рабочий начинает действовать после публикации сценария, а его запуски видны в разделе Executions. Ответ сервису можно отправить сразу, после завершения сценария или отдельным узлом.
Принимающий узел умеет разные методы запросов, от получения данных до их удаления, и несколько способов проверки: базовая авторизация, заголовок с секретом, токен JWT или открытый доступ. Открытый доступ допустим только для заведомо безопасных данных, во всех остальных случаях выбирайте проверку. Подробности и параметры лежат в справке по узлу Webhook.
От подборки готовых сценариев эта статья отличается уровнем: в материале n8n workflows описаны целые процессы, а здесь только входная дверь. Понятие вебхука и его отличие от обычного запроса объясняет глоссарий.
Условный пример: платёжный сервис присылает событие об оплате заказа. Сценарий принимает его, проверяет подпись, находит заказ и меняет статус. Если ответа от вас нет в течение отведённого времени, сервис повторит событие, и без защиты заказ будет отмечен оплаченным дважды, а клиенту уйдут два письма. Поэтому приём строят так, чтобы быстрый ответ уходил раньше долгой обработки.
Режим ответа выбирают по задаче. Мгновенный ответ подходит, когда сервис ждёт лишь подтверждения приёма. Ответ после завершения сценария нужен, если отправителю важен результат. Отдельный узел ответа даёт полный контроль над кодом и содержимым. Для долгих сценариев выбирайте мгновенный ответ и обрабатывайте событие после, иначе отправитель решит, что ответа нет, и пришлёт событие повторно. В облаке n8n запрос без ответа дольше 100 секунд завершается ошибкой 524, об этом предупреждает документация.
Подлинность запроса
Адрес вебхука секретом назвать нельзя: он попадает в журналы, переписки и конфигурации. Поэтому подлинность отправителя проверяют отдельно.
- Заголовок с секретом: отправитель добавляет общий секрет, узел сверяет его и отклоняет запрос с неверным значением.
- Подпись тела запроса: многие сервисы подписывают содержимое, и сценарий пересчитывает подпись и сравнивает; для этого подходит узел Crypto или код.
- Список разрешённых адресов: узел позволяет ограничить источники по IP, запросы извне получают отказ.
- Проверка формата: до любых действий убедитесь, что нужные поля на месте и имеют ожидаемый тип.
- Ограничение размера: по документации, запрос может весить до 16 МБ, на своём сервере предел меняет переменная N8N_PAYLOAD_SIZE_MAX, а лишние мегабайты от злоумышленника отсекаются.
Секреты храните в учётных данных n8n, а общий секрет отправителя меняйте по расписанию и сразу после ухода сотрудника, который его знал. Для каждого отправителя заводите отдельный адрес и отдельный секрет: если один сервис скомпрометирован, остальные продолжат работать, а отзыв секрета затрагивает только его.
Отказывайте быстро и однозначно: неверный секрет получает отказ без пояснений, что именно проверялось. Подробности об ошибке записывайте в журнал, а отправителю возвращайте сухой код. Принципы разделения прав между сценариями и внешними системами описаны в статье про n8n MCP и разделение прав.
Повторы и дубли
Доставка вебхуков обычно подразумевает «хотя бы один раз»: при сомнении отправитель повторяет событие. Поэтому сценарий должен давать одинаковый результат при повторной обработке одного и того же события. Это свойство называют идемпотентностью.
| Ситуация | Чем грозит | Как защититься |
|---|---|---|
| Отправитель повторил событие из-за таймаута | Двойная заявка, двойное письмо клиенту | Хранить идентификатор события и пропускать виденный |
| Два разных события об одном объекте | Конфликт: старое поверх нового | Сравнивать время или номер версии события |
| События пришли в другом порядке | Статус «оплачено» затёрт статусом «создан» | Состояние объекта только повышать, понижать запрещено |
| Сценарий упал на середине | Часть действий выполнена, часть нет | Делать шаги повторяемыми и записывать завершённые |
| Тестовый и рабочий запуски смешались | Тестовые данные попали в рабочие таблицы | Разные адреса, разные таблицы, метка среды |
В платформе есть узел Remove Duplicates, который умеет убирать элементы, уже обработанные в прошлых запусках. Вместо него подходит таблица со списком обработанных идентификаторов: запись создаётся в начале обработки и проверяется при каждом новом событии.
От каких сервисов вы принимаете вебхуки сейчас?
Журнал сбоев
Принятое событие нельзя терять, даже когда сценарий упал. Для этого сохраняют сырой запрос раньше любой логики и ведут журнал решений: принято, пропущено как дубль, отклонено, упало.
- Сразу после приёма запишите сырое тело и заголовки в таблицу или хранилище с отметкой времени и идентификатором события.
- Проверьте подлинность и формат, результат запишите рядом с событием: принято или отклонено с причиной.
- Определите дубль по идентификатору и отметьте его в журнале, чтобы потом сверять счётчики с отправителем.
- Подключите к рабочему сценарию отдельный сценарий на сбои, начинающийся с узла Error Trigger, и отправляйте в нём оповещение ответственному.
- Раз в неделю сверяйте журнал с данными отправителя: число принятых событий должно сходиться с числом отправленных.
Учитывайте и нагрузку. Всплеск событий, например при массовой рассылке на стороне отправителя, способен перегрузить сценарий. Выход — быстрый приём с записью в очередь и отдельный сценарий обработки, который разбирает очередь с собственной скоростью. Так всплеск превращается в задержку обработки, а потерянных событий нет.
Сырые запросы позволяют повторить обработку после исправления ошибки: вы берёте сохранённое событие и прогоняете его снова, без просьб к отправителю прислать данные заново. Храните их ограниченное время и учитывайте, что в запросах бывают персональные данные.
Разбор сбоя
Договоритесь с отправителем о правилах повтора: сколько раз он пробует, с какими паузами и какой код ответа считает успехом. Эти сведения есть в документации большинства сервисов, и без них вы гадаете, почему события приходят пачками или вовсе пропадают. Запишите правила рядом с настройками сценария, чтобы коллега мог разобраться без вас.
Если дважды отправить на рабочий адрес событие с одним идентификатором, в таблице должна остаться одна запись, а в журнале появиться отметка о дубле. Две записи означают, что защиты от повторов нет.
Если событие потеряно, идите по цепочке: дошёл ли запрос до сервера, зарегистрировал ли его узел, прошла ли проверка, что произошло дальше. Раздел запусков показывает, какие данные получил каждый узел, и по нему видно, где остановка. Если запроса нет в запусках вообще, ищите причину в сети, адресе или режиме публикации сценария.
О здоровье приёма говорит расхождение между числом событий у отправителя и числом записей у вас. Допустимое значение зависит от ценности событий, но любое ненулевое расхождение требует объяснения. Разовая проверка при настройке быстро устаревает: сервис меняет формат, ключ истекает, и поток тихо обрывается.
Входные контуры с журналами и оповещениями мы собираем в проектах по автоматизации бизнес-процессов.