n8n: как подключить вебхук, проверить подпись и защититься от дублей запросов - Блог Папы Карло

Эй, заглянул в мастерскую вовремя: стамески отдыхают, а вебхуки уже стучат в дверь. Я сегодня в роли Папы Карло на цифровом верстаке — собираем входящий webhook в n8n так, чтобы он не чудил, не принимал чужие запросы и не запускал одну и ту же автоматизацию по второму кругу.

Если нужен быстрый ответ, то рабочая схема такая: ставим узел Webhook, включаем Raw Body, сверяем подпись до любых действий, берём стабильный event_id, отсеиваем повторы через Remove Duplicates или Data Tables и отдаём ответ 200 пораньше через Respond to Webhook. Ниже покажу шаги, пример логики, таблицу выбора подхода и чек-лист перед запуском.

Что именно мы собираем

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

• принять запрос на свой endpoint;

• убедиться, что запрос пришёл от нужного отправителя;

• понять, не прилетел ли тот же event второй раз;

• ответить отправителю нормальным статусом;

• и только потом запускать полезную автоматику: запись в таблицу, уведомление, создание задачи, обновление CRM и всё остальное.

Самая частая беда тут такая: человек собрал Webhook, увидел первый успешный тест и расслабился. А потом прилетает повтор того же события, и workflow ещё раз шлёт сообщение, ещё раз создаёт запись или ещё раз дёргает API. В итоге бардак, лишние сущности и то самое лицо, когда “вроде всё работало”.

Я обычно держу в голове одну простую мысль: входящий вебхук — это не просто триггер. Это дверь в систему. На двери нужна проверка, а у самой двери нужен турникет, который режет повторный проход.

Шаг 1. Подключаем Webhook в n8n

Начинаю я обычно с самого каркаса. Создаёшь новый workflow, ставишь узел Webhook и задаёшь:

• HTTP Method — чаще всего POST;

• Path — внятный и короткий, к примеру /incoming/order-event;

• режим ответа — Using Respond to Webhook, если хочешь контролировать ответ сам;

• Raw Body — включить, если подпись считается по исходному телу запроса;

• IP whitelist — если отправитель работает с фиксированного набора адресов.

Важный момент: в n8n у Webhook есть тестовый URL и production URL. В тесте всё удобно для отладки, а в бою нужен активный workflow и production-адрес. Я не раз видел, как народ настраивает интеграцию на тестовый URL, гоняет пару удачных вызовов, а потом удивляется, почему в живом сценарии тишина.

Ещё один крепкий слой защиты — аутентификация на самом узле. Если сервис умеет стучаться через Basic auth, Header auth или JWT, я это включаю. Подпись запроса такая мера не заменяет, зато даёт дополнительный фильтр у входа.

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

Шаг 2. Готовим данные для проверки подписи

Теперь самое мясо. Подпись вебхука почти всегда завязана на двух вещах: секрет и точное содержимое запроса. И вот тут люди часто сами себе ставят подножку. Они берут уже распарсенный JSON, красиво меняют порядок полей, что-то приводят к строке — и на выходе получают подпись, которая уже не совпадает с той, что прислал отправитель.

Поэтому я действую так:

• беру исходное тело запроса в raw-виде;

• вытаскиваю подпись из заголовка;

• если провайдер добавляет timestamp или версию подписи, тоже вытаскиваю их в отдельные поля;

• сразу определяю будущий ключ идемпотентности: это может быть event_id, delivery_id, message_id или комбинация нескольких стабильных полей.

Обычно после Webhook я ставлю Set или Edit Fields и собираю служебные поля в одном месте. Пример логики такой:

raw_body = исходное тело запроса
incoming_signature = заголовок x-signature
incoming_timestamp = заголовок x-timestamp
event_id = body.id || headers["x-event-id"] || body.type + ":" + body.created_at

Если сервис подписывает строку вида timestamp + "." + raw_body, то именно такую строку и нужно собрать перед вычислением HMAC. Тут нужна дисциплина: подпись считается ровно по тому формату, который описан у отправителя.

Секрет я не держу в узле открытым текстом. Лучше использовать переменные, креды или внешний секрет-хранилище, если у тебя такая схема уже заведена. Чем меньше секретов лежит на виду, тем спокойнее потом сопровождать workflow.

Шаг 3. Проверяем подпись

Дальше два рабочих пути: через Crypto или через Code. Я чаще стартую с Crypto, потому что схема там читается глазами, а не только мозгом разработчика после третьей кружки кофе.

Вариант через Crypto

Если отправитель использует HMAC, цепочка выходит такая:

• Set — подготовить строку для подписи;

• Crypto — выбрать Hmac, нужный алгоритм, секрет и формат выдачи;

• IF — сравнить вычисленную подпись с той, что пришла в заголовке;

• Respond to Webhook — вернуть 401 или 403, если подпись не совпала.

Логика тут железная: пока подпись не сошлась, дальше по workflow никто не идёт. Никаких записей в базу, никаких уведомлений, никаких вызовов внешних сервисов. Сначала охрана на входе, потом всё остальное.

Если подпись считается по raw payload как по бинарным данным, Crypto это тоже тянет. В n8n можно считать HMAC по тексту или по бинарному файлу, так что под разные форматы входящих запросов решение есть.

Когда беру Code

Code я подключаю, когда схема подписи нетипичная: к примеру, нужно разбирать составной заголовок, нормализовать формат, вытащить версию, сверить допуск по времени и только потом запускать сравнение. В статье я бы всё равно начинал с Crypto, а Code держал бы как инструмент на случаи, где логика уже пошла в сторону кастомщины.

Вот пример ответа, который я люблю отдавать на неверную подпись:

{
  "ok": false,
  "message": "signature mismatch"
}

Тут не надо сочинять длинный роман. Достаточно короткого статуса, чтобы отправитель понял: запрос отклонён на этапе проверки.

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

Шаг 4. Ставим защиту от дублей

Теперь про вторую головную боль — дубли запросов. В реальном мире webhook-доставка часто работает по принципу “попробую ещё раз, если не дождался нормального ответа”. То есть один и тот же event может приехать повторно из-за задержки ответа, краткого сетевого сбоя или внутренней логики отправителя. n8n при этом видит просто новый входящий вызов и честно запускает workflow ещё раз.

Вот тут и нужна идемпотентность. На человеческом это значит: один и тот же event должен давать один и тот же результат, а не устраивать фейерверк из повторных действий.

Вариант А. Remove Duplicates

Если у тебя в payload уже есть стабильный идентификатор события, то это самый быстрый старт. Добавляешь Remove Duplicates и настраиваешь режим обработки повторов из прошлых execution. В качестве значения для сравнения ставишь свой event_id. На выходе свежие события идут дальше, а повторные — режутся на подлёте.

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

Вариант Б. Data Tables

Когда workflow важный, а событий много, я чаще смотрю в сторону Data Tables. Смысл простой: перед основным действием ищем запись с таким же event_id. Нашли — значит дубль. Не нашли — записываем событие и пропускаем дальше.

Что удобно хранить в таблице:

• event_id;

• source;

• received_at;

• signature_ok;

• краткий статус обработки.

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

Вариант В. Static data

Есть ещё путь через static data workflow. Я его использую аккуратно и только там, где поток событий спокойный. Для маленького хранилища вида “последние обработанные ключи” вариант годный, но на горячих входящих точках я бы не делал на него главную ставку. Для серьёзной нагрузки логичнее брать Data Tables или другое постоянное хранилище.

Мой практический совет такой: если только стартуешь, бери Remove Duplicates. Если workflow денежный, критичный или просто жирный по трафику — строй дедуп уже через таблицу.

Шаг 5. Отдаём ответ быстро

Очень полезный приём — вернуть 200 пораньше, когда ты уже успел проверить подпись и понять, что дубля нет. Для этого и хорош режим Using Respond to Webhook. Ты сам выбираешь момент ответа, а не ждёшь, пока вся цепочка докрутится до последнего узла.

Мой любимый паттерн такой:

1. Webhook принимает запрос.

2. Проверка подписи.

3. Проверка на дубль.

4. Respond to Webhook возвращает 200 и короткое тело ответа.

5. Дальше workflow уже делает тяжёлую работу.

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

Если прилетел дубль, я часто тоже отвечаю 200 с понятным статусом. Логика тут простая: событие уже обработано или уже принято в работу, значит для отправителя всё в порядке.

{
  "ok": true,
  "status": "duplicate_ignored"
}

Готовая схема workflow

Вот схема, которую я бы смело ставил в рабочий процесс:

Если у тебя есть действие, которое само умеет работать по ключу идемпотентности, я бы прокинул туда тот же event_id вторым контуром защиты. Лишним такое не бывает.

Где чаще всего спотыкаются

• Сравнивают подпись уже после того, как workflow успел что-то создать или отправить.

• Берут распарсенный JSON вместо исходного тела запроса.

• Используют случайный ключ вместо стабильного event_id для дедупа.

• Ставят дедуп уже после побочного действия, и он уже ни от чего не спасает.

• Возвращают ответ слишком поздно, и отправитель повторяет вызов.

• Тестируют всё на test URL, а в бою забывают переключиться на production URL.

• Хранят секрет в явном виде прямо в настройках узла, хотя можно унести его в более аккуратное место.

Я бы ещё добавил одну житейскую мысль: не надейся, что отправитель всегда идеален. Хороший webhook workflow строится так, будто внешний мир любит подкидывать дубли, задержки и странные заголовки.

Чек-лист перед запуском

• Webhook настроен на production URL и workflow активирован.

• Raw Body включён, если подпись зависит от исходного payload.

• Подпись проверяется до любых записей, уведомлений и API-вызовов.

• Секрет хранится аккуратно, а не торчит на весь экран.

• Выбран стабильный event_id для защиты от дублей.

• Remove Duplicates или таблица стоят до основной бизнес-логики.

• Respond to Webhook возвращает быстрый и понятный ответ.

• Для дублей предусмотрен мягкий сценарий ответа.

• Ошибочная подпись получает свой код и не проходит дальше.

Финал

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

Я бы советовал стартовать с простой и крепкой версии: Webhook → Set → Crypto → IF → Remove Duplicates → Respond to Webhook → основная логика. А дальше уже докручивать таблицы, хранение истории и более хитрые правила обработки, если поток событий вырастет.

Вот и вся столярка на сегодня: пару узлов подогнали, подпись прикрутили, дублям вход закрыли. Красота, стружка летит, workflow мурчит.