n8n → Hermes: elige una llamada a la API o un webhook de eventos

n8n es eficaz en la automatización predecible: recibe un evento, valida campos, llama a API, espera a personas y escribe resultados. Hermes Agent resulta útil cuando el siguiente paso exige interpretación, por ejemplo, para clasificar lenguaje, redactar una respuesta, investigar con herramientas o decidir qué significa «urgente» en un contexto determinado.

Hay dos patrones claros y tienen contratos diferentes. Si n8n necesita el resultado del agente para validarlo, guardarlo, aprobarlo o enviarlo, llama al servidor API de Hermes. Si n8n emite un evento y Hermes debe entregar el resultado a un destino configurado de Slack, Telegram, GitHub, correo electrónico u otro destino compatible, llama al adaptador de webhooks.

Consulta la documentación oficial del servidor API de Hermes, la documentación oficial de webhooks y el repositorio de NousResearch. Aquí no se documenta ningún nodo de n8n específico de Hermes y procedente del proyecto oficial; n8n utiliza su nodo genérico HTTP Request.

Un emisor genérico de n8n debe utilizar el contrato HMAC V2 de Hermes. Otros proveedores pueden tener una autenticación específica del adaptador, como la firma de GitHub o el token de GitLab. Cada ruta necesita el secreto que indique su documentación. INSECURE_NO_AUTH solo sirve para realizar pruebas en la interfaz de bucle local; la versión actual de Hermes se niega a arrancar con esa opción en una dirección que no sea de bucle local.

Cuándo transferir la tarea y cuándo mantenerla en n8n

Mantener en n8n

• Validación del esquema y ocultación de datos
• Claves de idempotencia y deduplicación (idempotencia y controles de aprobación humana)
• Conectores de CRM, correo electrónico y Slack con credenciales explícitas
• Colas de aprobación humana antes de cualquier envío externo
• Desencadenantes cron y webhook

Transferir a Hermes

• Clasificación ambigua que necesita contexto de documentos o repositorios
• Investigación en varios pasos con herramientas dentro del entorno de ejecución de Hermes y de acuerdo con su política de capacidades aceptada
• Redacción que debe utilizar memoria persistente o skills
• Investigación en corpus privados a los que el agente ya puede acceder

No transferir

• Enrutamiento puramente condicional que puedes expresar con nodos Switch
• Bucles de generación de gran volumen que deberían pasar primero por un clasificador más barato
• Secretos que n8n nunca debe reenviar, por ejemplo, tokens pegados en Hermes «por comodidad»

Si toda la tarea tiene forma de agente y se desencadena desde un chat, puede ser preferible una interfaz de pasarela. Consulta OpenClaw o Hermes según el trabajo. Para crear los primeros agentes en n8n sin Hermes, consulta un primer agente de IA en n8n.

Elige el contrato antes de construir

Resultado que necesita n8n:
Evento → n8n valida + reclama una clave duradera
      → HTTP Request (Bearer) → Hermes :8642/v1/responses o /v1/runs
      → n8n valida el resultado → aprobación humana → conector

Evento entregado por Hermes:
Evento → n8n valida + reclama una clave duradera
      → HTTP Request (HMAC V2) → Hermes :8644/webhooks/<name>
      → ejecución del agente Hermes → destino de entrega configurado

El servidor API escucha por defecto en 127.0.0.1:8642, exige API_SERVER_KEY y expone las rutas compatibles con OpenAI /v1/chat/completions y /v1/responses, además de la API Runs. Su clave da acceso a todo el conjunto de herramientas del agente Hermes, incluidas las operaciones de terminal y archivos. Mantén privada la dirección de escucha y controla estrictamente el cliente autorizado.

El adaptador de webhooks utiliza por defecto el puerto 8644. Su control de estado está en http://localhost:8644/health y sus rutas en /webhooks/<name>. Una ejecución por webhook envía su resultado al destino deliver configurado para la ruta. La lista documentada incluye plataformas de chat, comentarios de GitHub, correo electrónico, Home Assistant y log. No define un destino genérico de callback HTTP.

n8n sigue siendo responsable del estado duradero de los conectores SaaS y de los controles de aprobación humana. Hermes sigue siendo el paso acotado de razonamiento.

Contrato del evento webhook: pequeño y explícito

Evita enviar el árbol completo del elemento de n8n. Envía un objeto de tarea que el agente pueda procesar sin tener que adivinar.

Contrato ilustrativo:

{
  "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"
  }
}

Reglas:

1. Un resultado esperado por ruta, o una enumeración clara de los resultados posibles.
2. Conserva la clave duradera de la aplicación en n8n o en el sistema de negocio. Un campo del cuerpo puede correlacionar los registros, pero Hermes no lo utiliza como clave de deduplicación del webhook.
3. Envía un X-Request-ID estable cuando repitas la misma transferencia. Hermes guarda en caché los identificadores de entrega de los webhooks durante una hora y omite una ejecución o entrega duplicada dentro de ese periodo.
4. Indica qué no debe hacer el agente, por ejemplo, enviar, reembolsar o eliminar.
5. Prefiere los extractos a los archivos adjuntos completos. Almacena los objetos grandes en otro lugar y transmite únicamente referencias que Hermes esté autorizado a recuperar.

Crea una ruta de webhook de Hermes dedicada para cada familia de workflows (support-triage, ops-alert), con su propio prompt, filtros, secreto, skills y configuración de entrega. Trata cada campo de la carga útil como contenido no fiable. Aísla el entorno de ejecución, limita la plantilla del prompt, elimina las herramientas innecesarias y mantén las aprobaciones para las acciones destructivas o salientes.

Contrato HMAC V2 exacto de Hermes

Para un emisor genérico de n8n, la documentación actual de Hermes especifica V2:

• encabezado X-Webhook-Timestamp: segundos Unix;
• encabezado X-Webhook-Signature-V2: HMAC-SHA256 en hexadecimal minúscula;
• bytes firmados: <timestamp>.<raw-request-body>;
• ventana contra la repetición: la marca de tiempo debe estar dentro de ±300 segundos del reloj de Hermes.

La forma V1 X-Webhook-Signature, que solo cubre el cuerpo, sigue siendo compatible, pero no protege contra la repetición. No la utilices en workflows nuevos. Consulta el contrato de seguridad oficial.

Nodo de firma en un n8n autoalojado

Guarda HERMES_WEBHOOK_SECRET únicamente en el mecanismo de secretos o de entorno del proceso de n8n. No lo insertes en un nodo Set ni en el JSON de un workflow versionado. En un nodo Code, utiliza el módulo integrado de Node crypto solo si la configuración de n8n permite ese módulo y el acceso del nodo al entorno:

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 } }];

En un n8n autoalojado, permite únicamente el módulo integrado necesario conforme a la configuración actual de módulos del nodo Code. No habilites módulos externos arbitrarios. Con Task Runners externos, configura NODE_FUNCTION_ALLOW_BUILTIN=crypto como env-override en /etc/n8n-task-runners.json, no solo en el contenedor principal de n8n. El acceso a $env también depende de N8N_BLOCK_ENV_ACCESS_IN_NODE. Si tu política de seguridad lo impide, utiliza un servicio de firma aprobado por la organización o un nodo personalizado respaldado por secretos. No pegues el secreto en el workflow.

Configura el nodo HTTP Request de la siguiente manera:

No elijas el editor JSON estructurado del nodo HTTP después de firmar; volver a serializar podría cambiar los bytes. Rechaza cualquier respuesta que no sea 2xx. Una respuesta 200 puede significar entrega o duplicado, según la ruta y el identificador de entrega; no es un resultado estructurado del agente para n8n. No marques la clave duradera de n8n como completed solo porque Hermes haya aceptado o entregado el evento.

Incluso para webhooks de Hermes accesibles únicamente desde la LAN, utiliza la autenticación documentada. La proximidad de red no es autenticación. Los valores predeterminados actuales también limitan cada ruta de webhook a 30 solicitudes por minuto, rechazan cuerpos de más de 1 MB y guardan en caché los valores X-Request-ID o X-GitHub-Delivery durante una hora. Son controles de transporte limitados, no garantías duraderas de negocio.

El cuerpo del webhook suele contener mensajes de clientes. Mantén Hermes y n8n en redes privadas o en una superposición cifrada controlada. Prefiere una URL base de modelo local compatible con OpenAI para Hermes cuando el contenido deba permanecer dentro del perímetro aprobado; consulta los endpoints locales desde n8n. HMAC autentica al emisor, no a las personas que originaron los campos de negocio de la carga útil.

Qué se devuelve y quién realiza el envío

La interfaz elegida determina quién recibe el resultado.

A. Evento webhook con entrega gestionada por Hermes

La ruta ejecuta el agente y envía su respuesta al destino de entrega de Hermes configurado. n8n recibe un estado del adaptador, no la respuesta estructurada del agente. Utiliza este enfoque cuando el destino sea Slack, Telegram, GitHub, correo electrónico u otro destino documentado y ningún paso posterior de n8n necesite el contenido.

B. Resultado de la API devuelto a n8n

Llama a POST http://127.0.0.1:8642/v1/responses con Authorization: Bearer <API_SERVER_KEY> cuando n8n deba recibir la respuesta. Utiliza /v1/runs si el paso del agente debe enviarse y observarse como una ejecución en lugar de mantenerse como una única solicitud HTTP síncrona. La API escucha por defecto en la interfaz de bucle local y su clave bearer sigue siendo obligatoria.

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

Después de la llamada, n8n valida el esquema de la respuesta, la adjunta a la clave duradera de la aplicación y abre la puerta de aprobación humana. La caché de respuestas Idempotency-Key de la API de Hermes, que dura cinco minutos, puede hacer más seguros los reintentos inmediatos. No sustituye la reclamación duradera de n8n, una restricción de unicidad ni una transición de estado del negocio.

Modos de fallo

Utiliza Hermes MCP únicamente cuando Hermes deba realmente inspeccionar o gestionar una interfaz de n8n. Una llamada a una API HTTP o un webhook de eventos resulta más sencillo cuando ese es el contrato real.

Ejemplo: formulario de soporte → API de Hermes → aprobación humana

Camino feliz ilustrativo, sin afirmaciones sobre el despliegue ni el rendimiento:

1. El formulario del sitio envía una solicitud POST al webhook de n8n /support-intake.
2. n8n valida el correo electrónico, la longitud del mensaje y la enumeración del origen, y después reclama de forma duradera ticket-<uuid>.
3. n8n oculta campos si la política lo exige y construye la tarea acotada.
4. El nodo HTTP Request llama a /v1/responses de Hermes en el puerto 8642, con la credencial bearer y una clave Idempotency-Key de corta duración.
5. Hermes devuelve el resultado del agente a n8n.
6. n8n valida los campos obligatorios y guarda el borrador bajo la clave duradera del ticket.
7. Una persona aprueba o rechaza el borrador almacenado.
8. Solo un borrador aprobado llega al conector de correo electrónico o CRM de n8n.

Hermes no debe disponer de herramientas que permitan enviar en esta ruta. El prompt puede indicar «no enviar», pero la eliminación de esa capacidad y el conector controlado de n8n son las medidas que siguen funcionando si contenido no fiable intenta redirigir al agente.

Para un resumen interno de Slack que no vuelva a n8n, utiliza en su lugar la interfaz de webhook: configura deliver: slack, firma el evento, envía un X-Request-ID estable e interpreta la respuesta del adaptador únicamente como un estado de entrega.

Firma y desfase del reloj

Para la ruta de webhook:

• Serializa el JSON una sola vez, firma exactamente esos bytes y envía exactamente los mismos bytes.
• Sincroniza los relojes de n8n y Hermes; una firma V2 válida en los demás aspectos, pero fuera de la ventana de 300 segundos, se rechaza.
• La documentación oficial actual no define la aceptación simultánea de un secreto de webhook anterior y otro nuevo. Utiliza un cambio controlado o un procedimiento de rotación documentado para la versión desplegada.
• Registra los fallos de firma con el nombre de la ruta y un identificador de correlación no secreto. Nunca registres el secreto.

Si n8n se ejecuta en Docker y Hermes en el host, utiliza una dirección estable que sea accesible desde el espacio de nombres de red del proceso de n8n. En esta topología, localhost se refiere a espacios de nombres distintos.

Los callbacks personalizados son una integración independiente

La documentación actual de los webhooks de Hermes no incluye ningún destino genérico de callback HTTP. Si tu despliegue añade uno mediante código personalizado o una herramienta, descríbelo como una integración independiente y aplícale su propia lista fija de destinos permitidos, autenticación, validación de esquema, límite contra SSRF, idempotencia duradera y pruebas de aceptación. No des a entender que un campo callback en el cuerpo del webhook entrante activa una función integrada de Hermes.

Guía rápida de decisión

Orden mínimo de construcción

Para una ruta que devuelve un resultado de la API:

1. Habilita el servidor API en la interfaz de bucle local o en una interfaz privada y define API_SERVER_KEY.
2. Verifica el acceso autenticado a /v1/models y realiza una llamada de prueba a /v1/responses desde la red del entorno de ejecución de n8n.
3. Añade la validación del esquema de respuesta y una clave duradera de la aplicación en n8n.
4. Añade la puerta de aprobación humana antes de cualquier conector visible para el cliente.
5. Prueba los reintentos dentro y fuera de la caché de cinco minutos de la API.

Para una ruta de webhook de eventos:

1. Habilita el adaptador de webhooks y configura una ruta, un secreto, un prompt limitado, capacidades restringidas y un destino de entrega.
2. Verifica /health y envía un evento de prueba firmado con V2 desde la red del entorno de ejecución de n8n.
3. Envía un X-Request-ID estable y examina los estados de entrega y duplicado del adaptador.
4. Sustituye el desencadenante de prueba por el evento real validado y la clave duradera de n8n.
5. Prueba los límites de solicitudes y tamaño del cuerpo, la firma, el reloj, la entrega y la detención del servicio.

Pruebas de aceptación antes del tráfico de producción

Para la interfaz de la API, conserva pruebas de que una clave bearer ausente o incorrecta se rechaza, una solicitud de prueba devuelve el esquema esperado, un reintento inmediato con el mismo Idempotency-Key no provoca una segunda ejecución del agente, un reintento después de que caduque la caché de cinco minutos sigue bloqueado o se reconcilia mediante la clave duradera de la aplicación, la detención de Hermes genera un estado de espera visible y un borrador rechazado nunca llega a un conector de envío.

Para la interfaz de webhook, conserva pruebas de que se rechazan una solicitud sin firma, un cuerpo modificado después de firmarlo y una marca de tiempo fuera de la ventana de 300 segundos. Confirma que un evento de prueba firmado llega al destino de entrega configurado. Repítelo con el mismo X-Request-ID dentro de una hora y verifica un estado de duplicado sin una segunda ejecución ni una segunda entrega. Confirma después que n8n puede ver los fallos relacionados con el límite de solicitudes, un cuerpo demasiado grande, un destino no disponible y la detención de Hermes.

La integración solo está lista para un piloto cuando la interfaz pertinente supera sus pruebas de aceptación y las responsabilidades son explícitas. La autenticación bearer y HMAC establecen la identidad del llamante únicamente dentro de sus contratos documentados. La caché de cinco minutos de la API y la caché de una hora de los identificadores de entrega de webhooks son solo ayudas limitadas para los reintentos. La idempotencia duradera de la aplicación, la autorización, el estado de aprobación y la recuperación del negocio siguen siendo responsabilidad de n8n o del sistema de negocio.