n8n локально: вебхуки и Telegram Trigger через HTTPS-туннель

Настраиваем публичный URL для n8n на localhost: Docker Compose, N8N_WEBHOOK_URL, тестовый и рабочий webhook, Telegram Trigger и диагностика ошибок.

n8n может работать на http://localhost:5678, но внешний сервис не сможет вызвать этот адрес на вашем компьютере. Для входящих событий нужен публичный URL. В этом руководстве n8n остаётся локальным, а TunnelHunt передаёт к нему запросы через HTTPS-туннель.

Разберём сначала обычный Webhook node, затем Telegram Trigger. Так проще отделить проблему туннеля от настройки конкретной интеграции.

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

Если n8n ещё не установлен, начните с установки через Docker Compose: там разобраны постоянный том, проверка сохранения workflows, резервная копия и восстановление.

Нужны Docker с Compose, SSH-клиент с ключом и отдельное тестовое окружение n8n. Если у вас уже есть работающий n8n, сохраните его конфигурацию и данные: добавлять URL следует в существующий сервис, а не заменять весь Compose-файл примером ниже.

Чтобы использовать Free, добавьте публичный SSH-ключ в кабинет. Сессия без регистрации ограничена 15 минутами, Free — 4 часами. Для первой проверки платный тариф не требуется.

Инструкция использует N8N_WEBHOOK_URL для n8n 2.35.0 и новее. В более ранних версиях используется WEBHOOK_URL; начиная с 2.35.0 старое имя остаётся устаревшим алиасом. Это изменение описано в официальном справочнике переменных n8n.

1. Запустите n8n на localhost

Для нового тестового окружения создайте compose.yaml:

services:
  n8n:
    image: docker.n8n.io/n8nio/n8n:2.35.0
    ports:
      - "127.0.0.1:5678:5678"
    environment:
      GENERIC_TIMEZONE: Europe/Moscow
      TZ: Europe/Moscow
    volumes:
      - n8n_data:/home/node/.n8n

volumes:
  n8n_data:

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

docker compose up -d
docker compose logs --tail=50 n8n
curl -i http://127.0.0.1:5678/healthz

Дождитесь успешного запуска. Откройте http://localhost:5678 и завершите создание учётной записи владельца до открытия туннеля. Этот пример публикует весь HTTP-сервис n8n, включая страницу входа в редактор. Используйте тестовые credentials и защищённую учётную запись.

2. Получите HTTPS-адрес

Запустите SSH на той же машине, где опубликован Docker-порт:

ssh -p 2222 -o ExitOnForwardFailure=yes -R 80:127.0.0.1:5678 tunnelhunt.ru

Скопируйте выданный HTTPS-адрес. Оставьте SSH работающим. Если туннель не запускается, пройдите проверку публичного доступа к localhost.

3. Сообщите n8n внешний адрес

Добавьте в environment существующего сервиса две строки, заменив домен:

      N8N_WEBHOOK_URL: https://YOUR-SUBDOMAIN.tunnelhunt.ru/
      N8N_PROXY_HOPS: "1"

Затем пересоздайте контейнер с новой конфигурацией:

docker compose up -d n8n

Обычного docker compose restart недостаточно для применения изменённых переменных. Не удаляйте том n8n_data: в нём находятся данные окружения.

N8N_WEBHOOK_URL задаёт публичную основу URL. Локальный порт остаётся 5678; не меняйте его на 443 только потому, что внешний адрес использует HTTPS. N8N_PROXY_HOPS относится к доверию прокси-заголовкам. Для своей цепочки прокси проверьте настройку по инструкции n8n; не используйте её как гарантию подлинности IP отправителя.

4. Проверьте обычный Webhook node

Создайте новый workflow с узлом Webhook. Выберите метод POST, путь tunnelhunt-test и немедленный ответ. Для короткой проверки отправьте только искусственные данные; до подключения реальной системы настройте доступную в узле аутентификацию или проверку подписи отправителя.

Скопируйте Test URL из интерфейса. Он должен начинаться с вашего публичного HTTPS-домена, а не с localhost. Нажмите Listen for test event, затем отправьте запрос:

curl -i https://YOUR-SUBDOMAIN.tunnelhunt.ru/webhook-test/tunnelhunt-test \
  -H 'Content-Type: application/json' \
  --data '{"source":"tunnelhunt","message":"hello"}'

При неизменённых стандартных путях n8n данные появятся в выполнении узла, а HTTP-запрос получит успешный ответ. Если вы меняли пути endpoint, используйте URL, скопированный из интерфейса, целиком.

Проверьте не только HTTP-статус, но и входные данные узла: в body должны быть source: tunnelhunt и message: hello. Один ответ /healthz подтверждает доступ к сервису, но не выполнение workflow.

5. Перейдите от Test URL к Production URL

Тестовый адрес работает в режиме ожидания тестового события. Для постоянного приёма событий опубликуйте workflow — в старых версиях интерфейса это активация — и используйте Production URL.

У стандартной конфигурации путь изменится с /webhook-test/tunnelhunt-test на /webhook/tunnelhunt-test. Рабочие выполнения смотрите в Executions, даже если данные не появляются прямо на открытой схеме.

Различия режимов и варианты аутентификации описаны в документации Webhook node.

6. Подключите Telegram Trigger

Когда обычный webhook работает, создайте отдельного тестового бота через BotFather и добавьте его токен в Telegram credentials n8n. Добавьте Telegram Trigger, выберите событие сообщения и запустите тестовое ожидание. Отправьте боту сообщение из Telegram.

Webhook регистрирует сам n8n. Не вызывайте для этого же бота setWebhook вручную: вы можете заменить адрес, который установил Trigger. У одного бота только один текущий webhook; отдельные боты для разработки и рабочего окружения исключают конфликт регистрации.

Ошибка An HTTPS URL must be provided for webhook обычно означает, что n8n передал Telegram неподходящий URL. Проверьте переменную окружения, пересоздание контейнера и адрес, отображаемый узлом. Для самостоятельного обработчика без n8n есть инструкция по Telegram Bot API.

Как сохранить URL n8n после переподключения

Если меняется случайный домен, нужно обновить N8N_WEBHOOK_URL, пересоздать контейнер и заново включить приём событий. Для повторяющихся тестов Pro за 199 ₽/месяц даёт резервирование поддомена, 50 ГБ трафика в месяц и до 5 активных туннелей.

Сначала получите тестовое событие на Free по инструкции выше.
После активации Pro в кабинете откройте «Туннели», зарезервируйте свободный поддомен и привяжите SSH-ключ.
Переподключите SSH с этим ключом и проверьте выданный адрес. Укажите его в N8N_WEBHOOK_URL, сохранив завершающий /.
Пересоздайте контейнер и повторите тест Webhook node, затем Telegram Trigger.

Постоянное имя избавляет от изменения URL у отправителя. Оно не запускает n8n и не восстанавливает оборванный SSH. Восстановление соединения и доступность компьютера проверяются отдельно.

Что проверить, если события не приходят

Если «локальный n8n не работает с Telegram», разделите проверку на три шага. Сначала получите /healthz локально и через публичный адрес. Затем отправьте искусственное событие в обычный Webhook node. Только после этого проверяйте Telegram Trigger: так ошибка регистрации бота не смешивается с недоступностью контейнера.

Убедитесь, что контейнер получил нужные переменные. Следующая команда выводит только настройки URL и прокси, без credentials:

docker compose exec n8n sh -c 'printf "N8N_WEBHOOK_URL=%s\nWEBHOOK_URL=%s\nN8N_PROXY_HOPS=%s\n" "$N8N_WEBHOOK_URL" "$WEBHOOK_URL" "$N8N_PROXY_HOPS"'

Для используемой здесь версии задавайте N8N_WEBHOOK_URL; n8n_webhook_tunnel_url не является заменой этой переменной. Если в выводе старый домен, примените docker compose up -d n8n из каталога своего Compose-проекта и заново скопируйте URL из узла. Не публикуйте полный docker inspect или весь env-файл: там могут быть секреты.

Собственный WEBHOOK_SECRET из примера самостоятельного Telegram-бота не нужно вставлять в поле bot token у n8n. Credentials содержат bot token из BotFather, а регистрацию webhook выполняет Trigger. Если один бот используется и в n8n, и в другом приложении, последнее setWebhook заменяет адрес. Для test и production используйте отдельных тестовых ботов или переключайте окружения осознанно. Диагностика Telegram Trigger.

Симптом	Следующий шаг
`/healthz` локально не отвечает	Проверьте состояние контейнера и журнал запуска
Локально работает, снаружи `502`	Проверьте SSH-процесс и порт `5678` на его машине
В узле отображается `localhost`	Проверьте имя переменной для своей версии и пересоздайте контейнер
Ошибка, связанная с `X-Forwarded-For` или `trust proxy`	Проверьте `N8N_PROXY_HOPS` для фактической цепочки прокси; эта настройка не исправляет URL webhook
Тестовый URL возвращает `404`	Включите ожидание события и скопируйте URL ещё раз
Production URL возвращает `404`	Опубликуйте workflow, проверьте метод и путь
Telegram перестал отвечать после другого теста	Другой workflow мог заменить webhook этого бота
После переподключения пропали события	Случайный домен изменился; обновите URL или используйте резервируемый субдомен

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