n8n → Hermes: выберите вызов API или событийный вебхук

n8n силён в предсказуемой автоматизации: принять событие, проверить поля, вызвать API, подождать людей и записать результаты. Hermes Agent полезен, когда следующий шаг требует интерпретации, например разобрать язык триажа, набросать ответ, провести расследование с инструментами или решить, что значит «срочно» в контексте.

Есть два ясных паттерна, и у них разные контракты. Если n8n нужен результат агента для проверки, сохранения, согласования или отправки, вызывайте API-сервер Hermes. Если n8n испускает событие, а Hermes должен доставить результат в настроенный Slack, Telegram, GitHub, email или другую поддерживаемую цель, вызывайте адаптер вебхуков.

Используйте официальную документацию API-сервера Hermes, официальную документацию вебхуков и репозиторий NousResearch. Здесь не документирован специализированный узел n8n от Hermes; n8n использует универсальный узел HTTP Request.

Универсальный отправитель n8n должен использовать контракт Hermes V2 HMAC. У других поставщиков может быть аутентификация, специфичная для адаптера, например подпись GitHub или токен GitLab. Каждому маршруту нужен документированный секрет. INSECURE_NO_AUTH предназначен только для тестирования через loopback; текущая версия Hermes отказывается запускаться с ним на привязке не к loopback.

Когда передавать (и когда нет)

Оставляйте в n8n

• Валидация схемы и редактирование
• Ключи идемпотентности и дедупликация (идемпотентность и контрольные точки с участием человека)
• Коннекторы CRM, электронной почты и Slack с явно заданными учётными данными
• Очереди человеческого согласования до внешней отправки
• Триггеры по расписанию и вебхукам

Передавайте в Hermes

• Неоднозначная классификация, которой нужен контекст документов или репозитория
• Многошаговое исследование с инструментами в среде выполнения Hermes и в рамках принятой политики возможностей
• Черновики, которые должны использовать постоянную память или навыки
• Исследование по частным корпусам, до которых агент уже может достучаться

Не передавайте

• Простая маршрутизация «если, то», которую можно выразить узлами Switch
• Высокочастотные циклы генерации, перед которыми следует поставить более дешёвый классификатор
• Секреты, которые n8n не должен пересылать (например, передавать токены в Hermes «для удобства»)

Если вся задача имеет агентную структуру и запускается из чата, вам может больше подойти интерфейс шлюза. См. «OpenClaw или Hermes: выбирайте по задаче». О первых агентах n8n без Hermes см. статью «Ваш первый ИИ-агент в n8n».

Выберите контракт до начала разработки

n8n нужен результат:
Событие → n8n: валидация + устойчивое резервирование ключа
        → HTTP Request (Bearer) → Hermes :8642/v1/responses или /v1/runs
        → n8n проверяет результат → человек подтверждает → коннектор

Hermes доставляет событие:
Событие → n8n: валидация + устойчивое резервирование ключа
        → HTTP Request (V2 HMAC) → Hermes :8644/webhooks/<name>
        → запуск агента Hermes → настроенная цель доставки Hermes

API-сервер по умолчанию использует 127.0.0.1:8642, требует API_SERVER_KEY и предоставляет OpenAI-совместимые /v1/chat/completions, /v1/responses и Runs API. Ключ даёт доступ ко всему набору инструментов агента Hermes, включая операции терминала и файлов, поэтому сохраняйте привязку частной, а круг вызывающих клиентов узким.

Адаптер вебхуков по умолчанию использует порт 8644; его проверка работоспособности доступна по адресу http://localhost:8644/health, а маршруты находятся по пути /webhooks/<name>. Запуск вебхука отправляет результат в настроенную для маршрута цель deliver. Документированный список целей включает чат-платформы, комментарии GitHub, email, Home Assistant и log. Универсальная цель обратного HTTP-вызова не определена.

n8n остаётся владельцем устойчивого состояния для SaaS-коннекторов и контрольных точек с участием человека. Hermes выполняет ограниченный шаг рассуждения.

Контракт события вебхука: небольшой и явный

Не отправляйте агенту всё дерево элемента n8n. Передавайте объект задачи, с которым агент может работать без догадок.

Иллюстративный контракт:

{
  "application_key": "ticket-18422",
  "task": "Classify severity and draft a support reply. Do not send email.",
  "customer": {
    "name": "Example GmbH",
    "plan": "business"
  },
  "message": "VPN drops every morning around 09:00.",
  "constraints": {
    "output": "json",
    "fields": ["severity", "rationale", "draft_reply"],
    "language": "en"
  }
}

Правила:

1. Один ожидаемый исход на маршрут или один ясный enum исходов.
2. Храните устойчивый ключ приложения в n8n или бизнес-системе. Поле тела может коррелировать журналы, но Hermes не использует его как ключ дедупликации вебхука.
3. Отправляйте стабильный X-Request-ID для повторов одной и той же передачи. Hermes кэширует идентификаторы доставок вебхука в течение часа и пропускает повторный запуск или доставку внутри этого окна.
4. Указывайте, чего агент не должен делать, например отправлять, возвращать оплату или удалять.
5. Предпочитайте выдержки полным вложениям. Храните крупные объекты в другом месте и передавайте только ссылки, которые Hermes разрешено получать.

Создавайте отдельный маршрут вебхука Hermes для каждого семейства рабочих процессов (support-triage, ops-alert) со своим промптом, фильтрами, секретом, навыками и конфигурацией доставки. Считайте каждое поле полезной нагрузки недоверенным содержимым. Используйте песочницу, сужайте шаблон промпта, удаляйте ненужные инструменты и сохраняйте подтверждения для разрушительных или исходящих действий.

Точный контракт HMAC Hermes V2

Для универсального отправителя n8n текущая документация Hermes задаёт V2:

• заголовок X-Webhook-Timestamp: время в Unix-секундах;
• заголовок X-Webhook-Signature-V2: HMAC-SHA256 в нижнем регистре шестнадцатеричного формата;
• подписанные байты: <timestamp>.<raw-request-body>;
• окно защиты от повторов: метка времени должна находиться в пределах ±300 секунд от часов сервера Hermes.

Форма V1 X-Webhook-Signature (только тело сообщения) остаётся совместимой, но не обеспечивает защиту от повторов. Не используйте её для новых рабочих процессов. См. контракт безопасности в исходном репозитории.

Узел подписи для локально развёрнутого n8n

Храните HERMES_WEBHOOK_SECRET исключительно в механизме секретов или переменных окружения процесса n8n. Не помещайте его в узел Set или в коммитящийся JSON рабочего процесса. В узле Code используйте встроенный модуль Node crypto только в том случае, если конфигурация вашего n8n разрешает использование этого модуля и доступ узла к переменным окружения:

const { createHmac } = require('crypto');

const timestamp = Math.floor(Date.now() / 1000).toString();
const body = JSON.stringify($json.hermes_payload);
const secret = $env.HERMES_WEBHOOK_SECRET;

if (!secret) throw new Error('HERMES_WEBHOOK_SECRET is not configured');

const signature = createHmac('sha256', secret)
  .update(`${timestamp}.${body}`, 'utf8')
  .digest('hex');

return [{ json: { body, timestamp, signature } }];

Для локально развёрнутого n8n разрешайте только необходимый встроенный модуль в соответствии с текущей конфигурацией модулей узла Code; не включайте произвольные внешние модули. При использовании внешних Task Runners настройте NODE_FUNCTION_ALLOW_BUILTIN=crypto как env-override в /etc/n8n-task-runners.json, а не только в основном контейнере n8n. Доступ к $env также зависит от N8N_BLOCK_ENV_ACCESS_IN_NODE. Если политика безопасности блокирует доступ, используйте утверждённый организацией сервис подписи или пользовательский узел с поддержкой секретов. Не вставляйте секрет непосредственно в рабочий процесс.

Настройте узел HTTP Request следующим образом:

Не выбирайте структурированный JSON-редактор узла HTTP после подписания; повторная сериализация может изменить байты. Завершайте операцию с ошибкой при статусе ответа, отличном от 2xx. Ответ 200 может означать доставку или дубликат в зависимости от маршрута и идентификатора доставки; он не является структурированным результатом агента для n8n. Не помечайте устойчивый ключ n8n как completed только на основании того, что Hermes принял или доставил событие.

Для вебхуков Hermes только в LAN всё равно используйте документированную аутентификацию. Локальность сети не является аутентификацией. Текущие значения по умолчанию также ограничивают каждый маршрут вебхука 30 запросами в минуту, отклоняют тела размером более 1 МБ и кэшируют значения X-Request-ID или X-GitHub-Delivery в течение часа. Это ограниченные транспортные меры, а не устойчивые бизнес-гарантии.

Тело вебхука часто содержит клиентские сообщения. Держите Hermes и n8n в частных сетях или контролируемом зашифрованном оверлее. Предпочитайте для Hermes базовый URL локальной OpenAI-совместимой модели, когда содержимое должно оставаться внутри одобренной границы; см. статью о локальных конечных точках из n8n. HMAC аутентифицирует отправителя, а не людей, которые создали бизнес-поля внутри полезной нагрузки.

Что возвращается и кто отправляет

Поверхность определяет, кто получает результат.

A. Событие вебхука с доставкой под управлением Hermes

Маршрут запускает агента и отправляет ответ в настроенную цель доставки Hermes. n8n получает статус адаптера, а не структурированный ответ агента. Используйте этот вариант, когда целью является Slack, Telegram, GitHub, email или другая документированная система и ни одному последующему шагу n8n не требуется содержимое.

B. Результат API возвращается в n8n

Вызовите POST http://127.0.0.1:8642/v1/responses с Authorization: Bearer <API_SERVER_KEY>, когда n8n должен получить ответ. Используйте /v1/runs, когда агентский шаг следует отправить и наблюдать как запуск, а не удерживать в одном синхронном HTTP-запросе. API по умолчанию использует loopback, и bearer-ключ обязателен даже там.

{
  "model": "hermes-agent",
  "input": "Classify severity and draft a reply. Return the agreed JSON fields."
}

После вызова n8n проверяет схему ответа, связывает её с устойчивым ключом приложения и открывает контрольную точку для человека. Пятиминутный кэш ответа Idempotency-Key в API Hermes может сделать непосредственные повторы безопаснее. Он не заменяет устойчивое резервирование n8n, ограничение уникальности или переход бизнес-состояния.

Режимы отказа

Используйте Hermes MCP только тогда, когда Hermes действительно должен проверять или управлять поверхностью n8n. Вызов HTTP API или событийный вебхук проще, если именно таков фактический контракт.

Пример: форма поддержки → API Hermes → контрольная точка человека

Иллюстративный успешный сценарий без утверждений о развёртывании или производительности:

1. Форма сайта отправляет POST-запрос на вебхук n8n /support-intake.
2. n8n проверяет адрес электронной почты, длину сообщения и enum источника, затем устойчиво резервирует ключ ticket-<uuid>.
3. n8n скрывает поля, если этого требует политика, и составляет ограниченную задачу.
4. HTTP Request вызывает маршрут Hermes /v1/responses на порту 8642 с bearer-учётными данными и краткоживущим Idempotency-Key.
5. Hermes возвращает результат агента в n8n.
6. n8n проверяет обязательные поля и сохраняет черновик под устойчивым ключом заявки.
7. Согласующий принимает или отклоняет сохранённый черновик.
8. Только принятый черновик поступает в почтовый или CRM-коннектор n8n.

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

Для внутренней сводки Slack, которая не возвращается в n8n, используйте поверхность вебхука: настройте deliver: slack, подпишите событие, отправьте стабильный X-Request-ID и считайте ответ адаптера только статусом доставки.

Подпись и рассинхронизация часов

Для пути вебхука:

• Сериализуйте JSON один раз, подпишите именно эти байты и отправьте именно эти байты.
• Синхронизируйте часы n8n и Hermes; валидная подпись вне окна 300 секунд будет отклонена.
• Текущая официальная документация не определяет одновременное использование текущего и предыдущего секретов вебхука. Используйте контролируемое переключение или документированную для развёрнутой версии процедуру ротации.
• Логируйте сбои подписи с указанием имени маршрута и несекретного идентификатора корреляции. Никогда не записывайте сам секрет.

Если n8n работает в Docker, а Hermes на хосте, используйте стабильный адрес, маршрутизируемый из сетевого пространства имён процесса n8n. В такой топологии localhost относится к разным пространствам имён.

Пользовательские обратные вызовы являются отдельной интеграцией

Текущая документация вебхуков Hermes не перечисляет универсальную доставку обратным HTTP-вызовом. Если ваше развёртывание добавляет её через пользовательский код или инструмент, опишите её как отдельную интеграцию и задайте собственные фиксированный список разрешённых адресов, аутентификацию, проверку схемы, границу SSRF, устойчивую идемпотентность и приёмочные тесты. Не подразумевайте, что поле callback в теле входящего вебхука активирует встроенную функцию Hermes.

Шпаргалка решения

Минимальный порядок сборки

Для пути с результатом API:

1. Включите API-сервер на loopback или частном интерфейсе и задайте API_SERVER_KEY.
2. Проверьте аутентифицированный /v1/models и один пробный вызов /v1/responses из сети среды выполнения n8n.
3. Добавьте проверку схемы ответа и устойчивый ключ приложения n8n.
4. Добавьте контрольную точку человека перед любым коннектором, видимым клиенту.
5. Протестируйте повторы внутри и за пределами пятиминутного кэша API.

Для пути событийного вебхука:

1. Включите адаптер вебхуков и настройте один маршрут, секрет, узкий промпт, ограниченные возможности и цель доставки.
2. Проверьте /health и одно пробное событие с подписью V2 из сети среды выполнения n8n.
3. Отправьте стабильный X-Request-ID и проверьте статусы доставки и дубликата.
4. Замените пробный триггер реальным проверенным событием и устойчивым ключом n8n.
5. Протестируйте ограничения частоты и размера тела, подпись, часы, доставку и остановленный сервис.

Приёмочные тесты до запуска рабочего трафика

Для поверхности API сохраните доказательства, что отсутствующий или неверный bearer-ключ отклоняется; пробный запрос возвращает ожидаемую схему; немедленный повтор с тем же Idempotency-Key не создаёт второй запуск агента; повтор после пятиминутного кэша всё равно блокируется или согласуется устойчивым ключом приложения; остановленный Hermes создаёт видимое припаркованное состояние; отклонённый черновик никогда не достигает отправляющего коннектора.

Для поверхности вебхука сохраните доказательства, что неподписанный запрос, изменённое подписанное тело и временная метка вне 300-секундного окна отклоняются. Убедитесь, что подписанное пробное событие достигает настроенной цели доставки. Повторите его с тем же X-Request-ID в течение часа и проверьте статус дубликата без второго запуска агента или доставки. Затем убедитесь, что ошибки ограничения частоты, слишком большого тела, недоступной цели и остановленного Hermes видны n8n.

Интеграция готова к пилотному запуску только после прохождения приёмочных тестов соответствующей поверхности и при явном распределении ответственности. Bearer-аутентификация и HMAC устанавливают личность вызывающего только в пределах документированных контрактов. Пятиминутный кэш API и часовой кэш идентификаторов доставки вебхука являются ограниченными средствами для повторов. Устойчивая идемпотентность приложения, авторизация, состояние согласования и восстановление бизнеса остаются обязанностью n8n или бизнес-системы.