Webhooks and API integrations

Webhook — триггер, который создаёт HTTP-эндпоинт прямо в n8n. Настройки: HTTP Method (GET, POST, PUT...), Path (например, lead), Authentication (None, Basic Auth, Header Auth) и Respond — как отвечать вызывающему.

У каждой webhook-ноды ДВА адреса, и их путаница — ошибка номер один:

• Test URL (https://.../webhook-test/lead) работает, только пока в редакторе нажата Listen for test event; запрос виден сразу на canvas — идеально для отладки;
• Production URL (https://.../webhook/lead) начинает работать только после активации workflow, а прогоны попадают в список Executions, не в редактор.

Данные запроса раскладываются предсказуемо: тело — {{ $json.body }}, заголовки — {{ $json.headers }}, query-параметры — {{ $json.query }}.

curl -X POST https://n8n.example.com/webhook/lead \
  -H 'Content-Type: application/json' \
  -d '{"email":"ann@acme.io","company":"Acme"}'

После такого запроса {{ $json.body.email }} вернёт ann@acme.io. Для защиты эндпоинта минимум — Header Auth: n8n создаст credentials с именем и значением заголовка, и запросы без него получат отказ ещё до запуска workflow.

Параметр Respond у Webhook определяет, что получит вызывающий:

• Immediately — мгновенный ответ «Workflow got started», обработка идёт асинхронно; выбор для долгих задач;
• When Last Node Finishes — вернётся выход последней ноды workflow;
• Using Respond to Webhook Node — полный контроль: код, заголовки, тело.

Нода Respond to Webhook превращает n8n в маленький синхронный API. Минимальная конфигурация успешного ответа:

{
  "respondWith": "json",
  "options": { "responseCode": 201 }
}

Тело ответа собирается expression-ами из данных workflow — например, ={{ { "status": "ok", "leadId": $json.leadId } }}.

Паттерн mini-API: Webhook (Respond = Using Respond to Webhook Node) → валидация → бизнес-логика → Respond to Webhook с 201 и JSON-телом; отдельная ветка невалидного ввода → Respond to Webhook с 422 и описанием ошибки. Вызывающий всегда получает честный код состояния, а не универсальное 200.

Важное ограничение: HTTP-клиенты ждут ответа секунды, а не минуты. Если обработка долгая (LLM-цепочки, обход API с пагинацией) — отвечайте Immediately, а результат отправляйте отдельным исходящим запросом на callback-URL клиента. Синхронный ответ держите для операций быстрее примерно десяти секунд.

Когда готовой ноды-интеграции нет, HTTP Request закрывает практически любой API. Основные блоки: метод и URL, Send Query Parameters, Send Headers, Send Body (JSON, Form-Data, Raw). Киллер-фича для старта — Import cURL: вставьте curl-команду из документации API, и n8n сам заполнит все поля.

Аутентификация — всегда через credentials, никогда строкой в заголовке. Два режима: Predefined Credential Type — готовые схемы для сотен сервисов (GitHub, Slack, Stripe...), токен хранится шифрованно и не попадает в экспорт workflow; Generic Credential Type — Header Auth, Basic Auth, OAuth2 для остальных.

В Options спрятано то, что отличает игрушку от интеграции: Pagination — автоматический обход страниц по курсору или номеру страницы; Batching — Items per Batch и Batch Interval, чтобы не упереться в rate limit при сотне items на входе; Timeout — не ждать мёртвый сервис вечно. В Settings ноды живёт Retry On Fail (подробно — урок 5).

Антипаттерн: API-ключ прямо в URL (?api_key=sk-...) или в поле заголовка. Он утечёт при первом же экспорте JSON или шаринге workflow. Правильно: credentials + Predefined type, а в самой ноде — только логика запроса.

Приём чужих вебхуков (Stripe, GitHub, Telegram) — отдельная дисциплина, потому что эндпоинт публичный и запрос на него может прислать кто угодно.

Первое — проверка подлинности. Серьёзные сервисы подписывают payload: GitHub шлёт HMAC SHA-256 от тела запроса в заголовке X-Hub-Signature-256, Stripe — подпись с таймстампом в Stripe-Signature. В n8n проверка делается Code node сразу после Webhook: вычислите HMAC от raw body со своим секретом (модуль crypto) и сравните с заголовком; не совпало — ветка на Respond to Webhook с 401 и стоп. Секрет — в credentials или переменной окружения, не в коде.

Второе — дисциплина доставки. Отправители ретраят события при таймауте, поэтому: отвечайте быстро (Respond = Immediately), тяжёлую работу выносите в продолжение workflow; ждите дубликаты — одно и то же событие может прийти дважды, и обработчик обязан быть идемпотентным (инструменты — в уроке 5); не полагайтесь на порядок — событие «оплата» может прийти раньше «создан заказ».

Антипаттерн: синхронная цепочка из пяти внешних вызовов в обработчике вебхука. Таймаут отправителя истечёт, он пришлёт событие снова — получите и дубликаты, и двойную нагрузку.