Вебхуки в n8n: как принимать данные из CRM и с сайта

Вебхуком называют адрес, на который внешняя система сама отправляет данные, когда что-то происходит: пришла заявка с сайта, сделка перешла на этап, клиент оплатил счёт. Ниже настройка приёма в n8n, защита адреса и ответ отправителю, а также примеры для Тильды, amoCRM и Битрикс24.

Что понадобится

• n8n с доменом и HTTPS. Как его поставить, описано в инструкции по установке.
• Доступ к настройкам вебхуков во внешней системе: на сайте, в CRM или сервисе форм.

Шаг 1. Добавить узел Webhook

Создайте сценарий и первым узлом добавьте Webhook. Основные параметры:

• HTTP Method. Обычно POST. Узел также принимает GET, PUT, PATCH, DELETE и HEAD. Чтобы принимать несколько методов сразу, включите на вкладке Settings опцию Allow Multiple HTTP Methods.
• Path. Часть адреса после /webhook/. По умолчанию n8n подставляет случайную строку, её можно заменить на понятную, например tilda-lead. Одну пару из пути и метода может занимать только один вебхук.
• Authentication и Respond разобраны в шагах 3 и 4.

Шаг 2. Тестовый и рабочий адрес

Узел показывает два адреса:

https://n8n.example.ru/webhook-test/tilda-lead
https://n8n.example.ru/webhook/tilda-lead

Тестовый адрес работает 120 секунд после нажатия Listen for test event, пришедшие данные сразу видны в редакторе. Так удобно изучить структуру запроса.

Рабочий адрес начинает принимать запросы после публикации сценария кнопкой Publish (в версиях до 2.0 был переключатель Active). В редакторе данные не показываются, их видно на вкладке Executions.

Проверить вебхук можно с компьютера:

curl -X POST https://n8n.example.ru/webhook-test/tilda-lead \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Secret: ваш_секрет" \
  -d '{"name": "Тест", "phone": "+70000000000"}'

В узле тело запроса лежит в {{ $json.body }}, заголовки в {{ $json.headers }}, параметры строки запроса в {{ $json.query }}.

Шаг 3. Защитить адрес

Адрес вебхука публичный. Если его узнает посторонний, он сможет запускать ваш сценарий с любыми данными.

Header Auth. В Authentication выберите Header Auth и создайте учётные данные: в Name имя заголовка, например X-Webhook-Secret, в Value длинную случайную строку. Её удобно получить командой openssl rand -hex 24. Запрос без правильного заголовка получит ответ 403, сценарий не запустится.

Basic Auth. Логин и пароль. Подходит для систем, где в настройках вебхука есть такие поля. Без верных данных запрос получит 401.

Если система не умеет отправлять заголовки. Некоторые CRM передают секрет в теле запроса. Для них подойдут опции узла:

• Only Run If (n8n 2.28 и новее) запускает сценарий, только если выражение вернёт true. Остальные запросы получают ответ 200, запуск не создаётся.
• IP(s) Allowlist пропускает запросы только с перечисленных IP-адресов.

Случайный путь, который n8n подставляет по умолчанию, тоже затрудняет подбор адреса. Аутентификацию он не заменяет.

Шаг 4. Ответить отправителю

Параметр Respond определяет, когда и что n8n ответит:

• Immediately. Ответ 200 сразу после получения запроса. Подходит для CRM и сервисов форм, которые ждут ответа несколько секунд и при задержке повторяют отправку.
• When Last Node Finishes. Ответ после окончания сценария с данными последнего узла.
• Using ‘Respond to Webhook’ Node. Ответ формирует отдельный узел Respond to Webhook.

Третий вариант нужен, когда отправителю важен результат, например сайт показывает номер заявки. Поставьте Respond to Webhook после проверки данных, в Respond With выберите JSON и задайте тело:

{
  "status": "ok",
  "leadId": "{{ $json.id }}"
}

Код ответа меняется в опции Response Code. Если сценарий упадёт до этого узла, отправитель получит ответ 500. Узел отвечает один раз и по первому элементу, второй такой узел будет проигнорирован.

Шаг 5. Работа за прокси

Если n8n стоит за Caddy или Nginx, укажите публичный адрес в настройках n8n:

N8N_WEBHOOK_URL: https://n8n.example.ru/
N8N_PROXY_HOPS: 1

С версии 2.35 переменная называется N8N_WEBHOOK_URL. Старое имя WEBHOOK_URL пока работает, n8n только пишет предупреждение в журнал. Без этой переменной n8n покажет адрес вида http://localhost:5678/webhook/..., и внешние системы не смогут его вызвать. N8N_PROXY_HOPS нужна, чтобы n8n видел настоящий IP отправителя. Прокси при этом должен передавать заголовки X-Forwarded-For, X-Forwarded-Host и X-Forwarded-Proto.

Пример 1. Форма на Тильде

1. Узел Webhook: метод POST, путь tilda-lead, Respond: Immediately, аутентификация Header Auth с именем заголовка, например X-Api-Key.
2. В Тильде откройте Настройки сайта → Формы → Webhook и укажите адрес вебхука. В настройках приёмщика задайте имя ключа API X-Api-Key, его значение и способ передачи в заголовках.
3. В настройках блока с формой отметьте Webhook и опубликуйте страницу.

Сразу после подключения Тильда отправляет проверочный запрос test=test и ждёт ответа 200 OK. Чтобы он не создавал запуск, добавьте в Only Run If выражение:

{{ $json.body.test !== 'test' }}

Перед переключением на рабочий адрес подключите тестовый и проверьте в редакторе, что заголовок с ключом приходит.

Поля формы приходят в теле запроса под именами переменных из настроек формы: {{ $json.body.Name }}, {{ $json.body.Phone }}, {{ $json.body.Email }}. Дополнительно приходят tranid (номер заявки) и formid (номер блока).

Тильда ждёт ответа не дольше пяти секунд. Если ответа нет, она повторит отправку ещё два раза с интервалом в минуту. Поэтому отвечайте сразу и отсеивайте повторы по tranid.

Пример 2. Вебхук из CRM

amoCRM. Вебхук настраивается в разделе амоМаркет → WEB HOOKS или действием «Отправить webhook» на этапе цифровой воронки. Данные приходят в формате x-www-form-urlencoded. amoCRM ждёт ответа не больше 2 секунд и при ошибке повторяет отправку. После большого числа неудачных ответов вебхук отключается. Поэтому ставьте Respond: Immediately.

n8n разбирает такие данные в плоские ключи, поэтому ID сделки при смене этапа берётся так:

{{ $json.body['leads[status][0][id]'] }}

Точные имена ключей посмотрите в тестовом запуске. Как работать с API amoCRM дальше, описано в статье об amoCRM и n8n.

Битрикс24. Исходящий вебхук создаётся в разделе Приложения → Разработчикам → Готовые сценарии → Другое → Исходящий вебхук: адрес обработчика и событие, например ONCRMDEALUPDATE. Битрикс24 присылает только ID объекта и токен для проверки:

{{ $json.body['data[FIELDS][ID]'] }}
{{ $json.body['auth[application_token]'] }}

Сравнивайте токен со значением из настроек вебхука в опции Only Run If. Полные данные сделки запрашивайте отдельным запросом к REST API, подробнее в статье о Битрикс24 и n8n.

Частые ошибки

• 404 на рабочем адресе. Сценарий не опубликован, или во внешней системе остался тестовый адрес с /webhook-test/.
• В адресе localhost. Не задана переменная N8N_WEBHOOK_URL или WEBHOOK_URL.
• 403. Неверное имя или значение заголовка для Header Auth.
• Дубли заявок. Отправитель не дождался ответа и повторил запрос. Отвечайте сразу и проверяйте уникальный номер заявки.
• Пустой body. Данные пришли методом GET в параметрах строки, ищите их в $json.query.
• IP(s) Allowlist блокирует свои же запросы. n8n за прокси видит IP прокси. Задайте N8N_PROXY_HOPS.
• Ошибка на больших файлах. По умолчанию вебхук принимает до 16 МБ. Лимит меняется переменной N8N_PAYLOAD_SIZE_MAX.

Справка по узлам: Webhook, Respond to Webhook, вебхуки Тильды.