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

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

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

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

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

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

Инструкция использует 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, скопированный из интерфейса, целиком.

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.

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

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

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