n8n webhook на localhost: HTTPS-адрес для локального workflow

Внешняя CRM не отправит событие на localhost:5678: этот адрес относится к компьютеру самого отправителя. Чтобы локальный n8n принимал вебхуки из интернета, нужен публичный HTTPS-адрес. Откройте HTTP-туннель fxTunnel на порт n8n, задайте публичную основу webhook URL и проверьте один POST сначала локально, затем через туннель.

1. Подготовьте локальный n8n

Пример рассчитан на self-hosted n8n, работающий на вашем компьютере. Установку выберите по документации n8n. Если n8n уже запущен, откройте http://localhost:5678, войдите в редактор и проверьте, что можете создать workflow. При первом запуске закончите настройку аккаунта владельца.

В терминале с установленным n8n:

n8n --version
n8n start

Для Docker используйте свою команду запуска контейнера. Порт n8n должен быть доступен на машине, где работает fxTunnel; типичная привязка для локального стенда 127.0.0.1:5678:5678. В контейнере localhost относится к самому контейнеру. В этом примере клиент fxTunnel запускается на хосте, а не внутри Docker.

Сохраните версию n8n: она понадобится при выборе имени переменной на шаге 4. Если ваша установка слушает другой порт, замените 5678 в командах.

2. Создайте POST-вебхук и проверьте его без туннеля

Добавьте узел Webhook в новый workflow. Выберите HTTP Method: POST, путь crm-demo и ответ Immediately. Для проверки используйте Authentication: Header auth и создайте credential с именем заголовка X-Demo-Token и значением local-demo-token. Это тестовый секрет; для интеграции замените его своим. Настройка описана в документации Webhook credentials.

Нажмите Listen for test event и отправьте запрос из другого терминала. Многострочные команды curl рассчитаны на Bash, включая Git Bash на Windows:

curl --fail-with-body -i \
  'http://localhost:5678/webhook-test/crm-demo' \
  -H 'Content-Type: application/json' \
  -H 'X-Demo-Token: local-demo-token' \
  -d '{"event":"demo","customer_id":42}'

-d выбирает POST. В PowerShell JSON соберите через ConvertTo-Json:

$body = @{event='demo'; customer_id=42} | ConvertTo-Json -Compress
$headers = @{'X-Demo-Token'='local-demo-token'}
$response = Invoke-WebRequest -UseBasicParsing -Uri 'http://localhost:5678/webhook-test/crm-demo' -Method Post -ContentType 'application/json' -Headers $headers -Body $body
$response.StatusCode

Ожидается HTTP 200; в тестовом выполнении Webhook должны появиться event: demo и customer_id: 42 внутри body. Так вы проверите приём POST без участия туннеля.

Тестовый слушатель ограничен по времени. Если получили 404, снова нажмите Listen for test event и повторите POST. Для следующего теста также включайте слушатель заново. Порядок тестирования описан в документации workflow.

3. Установите fxTunnel и выберите адрес

На странице скачивания доступны CLI и GUI. В графическом клиенте создайте HTTP-туннель на порт 5678 и выберите поддомен. Для работы через терминал используйте CLI; команды ниже относятся к нему.

На Linux и macOS:

curl -fsSL https://fxtun.ru/install.sh | sh
fxtunnel login
fxtunnel http 5678 --domain n8n-hook

На Windows установите клиент, затем выполните вход и команду HTTP-туннеля в PowerShell. Вход можно пройти через браузер или API-токен.

Имя n8n-hook условное: выберите свободное и возьмите HTTPS-адрес из вывода клиента. Далее для примера используем https://n8n-hook.fxtun.ru. Сохраните своё имя во всех настройках и командах, не закрывайте окно клиента.

Туннель на порт n8n открывает доступ и к редактору этого экземпляра. Оставьте его авторизацию включённой. Вебхук имеет отдельную авторизацию, заданную в узле; пароль редактора её не заменяет.

4. Задайте публичную основу webhook URL

n8n должен показывать адрес туннеля в узле Webhook. Для версий от 2.35 используйте N8N_WEBHOOK_URL; в более ранних версиях переменная называется WEBHOOK_URL. С версии 2.35 старое имя поддерживается как устаревший alias. Это указано в справочнике переменных.

Остановите n8n и запустите его с переменными окружения. Для установленного CLI версии 2.35 или новее:

export N8N_WEBHOOK_URL=https://n8n-hook.fxtun.ru/
export N8N_PROXY_HOPS=1
n8n start

В PowerShell:

$env:N8N_WEBHOOK_URL="https://n8n-hook.fxtun.ru/"
$env:N8N_PROXY_HOPS="1"
n8n start

Для старого n8n замените имя N8N_WEBHOOK_URL на WEBHOOK_URL. В Docker Compose внесите переменные в environment сервиса n8n и пересоздайте контейнер, например docker compose up -d n8n, если сервис у вас называется n8n. После изменения переменных уже работающий контейнер нужно пересоздать.

N8N_PROXY_HOPS=1 соответствует одному прокси перед n8n в этом примере. Если между fxTunnel и n8n есть ваш nginx, конфигурацию доверенных прокси и заголовки нужно сверить с фактической цепочкой. n8n требует корректные X-Forwarded-For, X-Forwarded-Host и X-Forwarded-Proto. Публичная основа URL задаёт адрес вебхуков; настройки редактора и его авторизации остаются отдельными.

Перезагрузите страницу редактора. В Test URL и Production URL должен стоять ваш HTTPS-домен, без localhost и порта 5678.

5. Проверьте запрос через HTTPS

Снова нажмите Listen for test event. Повторите локальный тест, заменив только адрес:

curl --fail-with-body -i \
  'https://n8n-hook.fxtun.ru/webhook-test/crm-demo' \
  -H 'Content-Type: application/json' \
  -H 'X-Demo-Token: local-demo-token' \
  -d '{"event":"demo","customer_id":42}'

В PowerShell повторите Invoke-WebRequest с публичным адресом, сохранив $headers и $body:

$response = Invoke-WebRequest -UseBasicParsing -Uri 'https://n8n-hook.fxtun.ru/webhook-test/crm-demo' -Method Post -ContentType 'application/json' -Headers $headers -Body $body
$response.StatusCode

Проверьте HTTP 200 и данные запроса в тестовом выполнении. Они показывают, что POST прошёл по HTTPS через туннель в локальный workflow. Если ответ успешный, а данные не видны, проверьте, какой экземпляр n8n и какой workflow получили запрос.

6. Перейдите на Production URL

Сохраните и опубликуйте workflow; в старых версиях интерфейса нужно включить Active. Затем скопируйте Production URL непосредственно из узла Webhook. При стандартных настройках Production использует путь /webhook/crm-demo. У Test путь /webhook-test/crm-demo.

Повторите POST на Production URL с тем же заголовком и телом. Результат рабочего запуска ищите во вкладке Executions, а не в тестовом окне узла. Документация Webhook различает эти режимы: Test работает во время отладки, Production принимает запросы опубликованного workflow.

В CRM или другой внешней системе сохраняйте весь Production URL с путём. Метод, формат тела и способ авторизации должны совпадать с настройкой отправителя. Наш пример использует JSON и собственный заголовок; исходящий вебхук Битрикс24 отправляет форму и application_token. Для него есть отдельный пример обработчика. Проверку токена или подписи отправителя сохраните в своём workflow.

Когда резервировать имя

Для первого успешного POST достаточно бесплатного HTTP-туннеля со свободным именем. После выключения такое имя может занять другой пользователь. Если Production URL уже записан в CRM, резерв на Base и выше сохранит имя между запусками:

fxtunnel domains add n8n-hook
fxtunnel http 5678 --domain n8n-hook

Резерв закрепляет имя, но для доставки событий n8n и клиент fxTunnel должны работать. Для собственного домена и нескольких параллельных стендов смотрите тарифы и постоянный адрес туннеля.

Inspector на Base и выше показывает запрос и ответ. Обычный адрес http://127.0.0.1:4040; точный порт указан в строке Inspector: клиента. Replay повторно запускает обработку: используйте тестовые данные и защиту от дублей перед рабочими действиями. Подробнее: отладка запросов.

Если запрос не пришёл