n8n → Hermes : choisir entre un appel API et un webhook événementiel

n8n excelle dans l’automatisation prévisible : recevoir un événement, valider des champs, appeler des API, attendre une intervention humaine et écrire des résultats. Hermes Agent est utile lorsque l’étape suivante demande une interprétation, par exemple pour trier des messages, rédiger une réponse, mener une investigation avec des outils ou déterminer ce que signifie « urgent » dans un contexte donné.

Il existe deux modèles bien délimités, aux contrats différents. Si n8n a besoin du résultat de l’agent pour le valider, l’enregistrer, l’approuver ou l’envoyer, appelez le serveur API Hermes. Si n8n émet un événement et que Hermes doit livrer le résultat vers une destination Slack, Telegram, GitHub, e-mail ou autre destination prise en charge et configurée, appelez l’adaptateur webhook.

Consultez la documentation officielle du serveur API Hermes, la documentation officielle des webhooks et le dépôt NousResearch. Aucun nœud n8n propre à Hermes n’est documenté ici par le projet officiel ; n8n utilise son nœud générique HTTP Request.

Un émetteur n8n générique doit utiliser le contrat HMAC V2 de Hermes. D’autres fournisseurs peuvent appliquer une authentification propre à leur adaptateur, par exemple la signature de GitHub ou le jeton de GitLab. Chaque route exige son secret documenté. INSECURE_NO_AUTH est réservé aux tests sur l’interface de bouclage ; dans sa version actuelle, Hermes refuse de démarrer avec cette option sur une adresse qui n’est pas de bouclage.

Quand transférer la tâche, et quand la garder dans n8n

À conserver dans n8n

• Validation du schéma et caviardage
• Clés d’idempotence et déduplication (idempotence et validations humaines)
• Connecteurs CRM, e-mail et Slack avec des identifiants explicites
• Files d’approbation humaine avant tout envoi externe
• Déclencheurs cron et webhook

À confier à Hermes

• Classification ambiguë qui demande le contexte d’un document ou d’un dépôt
• Investigation en plusieurs étapes avec des outils, dans l’environnement d’exécution de Hermes et selon sa politique de capacités acceptée
• Rédaction qui doit utiliser une mémoire persistante ou des skills
• Recherche dans des corpus privés auxquels l’agent a déjà accès

À ne pas transférer

• Routage purement conditionnel que vous pouvez exprimer avec des nœuds Switch
• Boucles de génération à fort volume qui devraient d’abord passer par un classifieur moins coûteux
• Secrets que n8n ne doit jamais transmettre, par exemple des jetons collés dans Hermes « pour simplifier »

Si toute la tâche suit une logique d’agent et démarre dans une conversation, une interface de passerelle peut être préférable. Consultez OpenClaw ou Hermes selon la tâche. Pour créer de premiers agents n8n sans Hermes, consultez un premier agent d’IA dans n8n.

Choisir le contrat avant de construire

Résultat requis par n8n :
Événement → n8n valide + réserve durablement la clé
      → HTTP Request (Bearer) → Hermes :8642/v1/responses ou /v1/runs
      → n8n valide le résultat → validation humaine → connecteur

Événement livré par Hermes :
Événement → n8n valide + réserve durablement la clé
      → HTTP Request (HMAC V2) → Hermes :8644/webhooks/<name>
      → exécution de l’agent Hermes → destination Hermes configurée

Le serveur API écoute par défaut sur 127.0.0.1:8642, exige API_SERVER_KEY et expose les routes compatibles OpenAI /v1/chat/completions, /v1/responses ainsi que l’API Runs. Sa clé donne accès à l’ensemble des outils de l’agent Hermes, notamment aux opérations sur le terminal et les fichiers. Gardez donc l’adresse d’écoute privée et contrôlez strictement le client autorisé.

L’adaptateur webhook utilise par défaut le port 8644. Son contrôle d’état se trouve à l’adresse http://localhost:8644/health, et ses routes sous /webhooks/<name>. Une exécution webhook envoie son résultat vers la cible deliver configurée pour la route. La liste documentée comprend les plateformes de discussion, les commentaires GitHub, l’e-mail, Home Assistant et log. Elle ne définit pas de cible de rappel HTTP générique.

n8n reste propriétaire de l’état durable des connecteurs SaaS et des validations humaines. Hermes reste l’étape de raisonnement bornée.

Contrat d’événement webhook : petit et explicite

Évitez de transmettre l’arborescence complète de l’item n8n. Envoyez un objet de tâche que l’agent peut traiter sans devoir deviner.

Exemple de contrat :

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

Règles :

1. Une sortie attendue par route, ou une énumération claire des sorties possibles.
2. Conservez la clé applicative durable dans n8n ou dans le système métier. Un champ du corps peut corréler les journaux, mais Hermes ne l’utilise pas comme clé de déduplication du webhook.
3. Envoyez un X-Request-ID stable lorsque vous réessayez le même transfert. Hermes met en cache les ID de diffusion des webhooks pendant une heure et ignore toute nouvelle exécution ou livraison portant le même identifiant pendant cette période.
4. Indiquez ce que l’agent ne doit pas faire, par exemple envoyer, rembourser ou supprimer.
5. Préférez les extraits aux pièces jointes complètes. Stockez les objets volumineux ailleurs et ne transmettez que des références que Hermes est autorisé à récupérer.

Créez une route webhook Hermes dédiée à chaque famille de flux de travail (support-triage, ops-alert), avec son propre prompt, ses filtres, son secret, ses skills et sa configuration de diffusion. Traitez chaque champ de la charge utile comme du contenu non fiable. Isolez l’environnement d’exécution, restreignez le modèle de prompt, retirez les outils inutiles et conservez les approbations pour les actions destructrices ou sortantes.

Contrat HMAC V2 exact de Hermes

Pour un émetteur n8n générique, la documentation actuelle de Hermes spécifie V2 :

• en-tête X-Webhook-Timestamp : secondes Unix ;
• en-tête X-Webhook-Signature-V2 : HMAC-SHA256 en hexadécimal minuscule ;
• octets signés : <timestamp>.<raw-request-body> ;
• fenêtre contre le rejeu : l’horodatage doit se situer à ±300 secondes de l’horloge de Hermes.

La forme V1 X-Webhook-Signature, qui ne couvre que le corps, reste compatible, mais ne protège pas contre le rejeu. Ne l’utilisez pas pour de nouveaux flux de travail. Consultez le contrat de sécurité officiel.

Nœud de signature dans un n8n auto-hébergé

Stockez HERMES_WEBHOOK_SECRET uniquement dans le mécanisme de secrets ou d’environnement du processus n8n. Ne l’insérez ni dans un nœud Set ni dans le JSON d’un flux de travail versionné. Dans un nœud Code, utilisez le module Node intégré crypto uniquement si votre configuration n8n autorise ce module et l’accès du nœud à l’environnement :

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

Pour un n8n auto-hébergé, n’autorisez que le module intégré nécessaire, conformément à la configuration actuelle des modules du nœud Code. N’activez pas de modules externes arbitraires. Avec les Task Runners externes, configurez NODE_FUNCTION_ALLOW_BUILTIN=crypto comme env-override dans /etc/n8n-task-runners.json, et pas uniquement dans le conteneur n8n principal. L’accès à $env dépend aussi de N8N_BLOCK_ENV_ACCESS_IN_NODE. Si votre politique de sécurité l’interdit, utilisez un service de signature approuvé par votre organisation ou un nœud personnalisé adossé à un gestionnaire de secrets. Ne collez pas le secret dans le flux de travail.

Configurez le nœud HTTP Request comme suit :

Après la signature, ne choisissez pas l’éditeur JSON structuré du nœud HTTP : une nouvelle sérialisation pourrait modifier les octets. Traitez tout code autre que 2xx comme un échec bloquant. Une réponse 200 peut signifier que l’événement a été livré ou détecté comme doublon, selon la route et l’identifiant de livraison. Il ne s’agit pas d’un résultat structuré de l’agent destiné à n8n. Ne marquez pas la clé durable n8n comme completed uniquement parce que Hermes a accepté ou livré l’événement.

Même pour des webhooks Hermes accessibles uniquement sur le réseau local, utilisez l’authentification documentée. La proximité réseau ne constitue pas une authentification. Les valeurs par défaut actuelles limitent aussi chaque route webhook à 30 requêtes par minute, refusent les corps de plus de 1 Mo et mettent en cache les valeurs X-Request-ID ou X-GitHub-Delivery pendant une heure. Ce sont des contrôles de transport bornés, pas des garanties métier durables.

Le corps du webhook contient souvent des messages de clients. Gardez Hermes et n8n sur des réseaux privés ou sur une couche chiffrée contrôlée. Préférez une URL de base de modèle locale et compatible OpenAI pour Hermes lorsque le contenu doit rester dans votre périmètre approuvé ; consultez les points de terminaison locaux depuis n8n. HMAC authentifie l’émetteur, pas les personnes à l’origine des champs métier dans la charge utile.

Ce qui est renvoyé et qui effectue l’envoi

L’interface choisie détermine qui reçoit le résultat.

A. Événement webhook avec diffusion gérée par Hermes

La route exécute l’agent et envoie sa réponse vers la cible de diffusion Hermes configurée. n8n reçoit un état de l’adaptateur, pas la réponse structurée de l’agent. Utilisez cette approche lorsqu’une destination Slack, Telegram, GitHub, e-mail ou autre destination documentée doit recevoir le résultat et qu’aucune étape ultérieure de n8n n’a besoin de son contenu.

B. Résultat API renvoyé à n8n

Appelez POST http://127.0.0.1:8642/v1/responses avec Authorization: Bearer <API_SERVER_KEY> lorsque n8n doit recevoir la réponse. Utilisez /v1/runs si l’étape de l’agent doit être soumise et observée comme une exécution au lieu d’occuper une seule requête HTTP synchrone. L’API écoute par défaut sur l’interface de bouclage, et même là, sa clé bearer reste obligatoire.

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

Après l’appel, n8n valide le schéma de la réponse, l’attache à la clé applicative durable et ouvre la validation humaine. Le cache de réponse Idempotency-Key de l’API Hermes, valable cinq minutes, peut sécuriser les nouvelles tentatives immédiates. Il ne remplace ni la revendication durable dans n8n, ni une contrainte d’unicité, ni une transition d’état métier.

Modes d’échec

Utilisez Hermes MCP uniquement lorsque Hermes doit réellement inspecter ou piloter une interface n8n. Un appel API HTTP ou un webhook événementiel est plus simple lorsque tel est le contrat réel.

Exemple : formulaire d’assistance → API Hermes → validation humaine

Exemple de chemin nominal, sans affirmation sur le déploiement ni les performances :

1. Le formulaire du site envoie une requête POST au webhook n8n /support-intake.
2. n8n valide l’e-mail, la longueur du message et l’énumération de la source, puis revendique durablement ticket-<uuid>.
3. n8n caviarde les champs si la politique l’exige et construit la tâche bornée.
4. Le nœud HTTP Request appelle /v1/responses de Hermes sur le port 8642, avec le jeton bearer et une clé Idempotency-Key de courte durée.
5. Hermes renvoie le résultat de l’agent à n8n.
6. n8n valide les champs requis et enregistre le brouillon sous la clé durable du ticket.
7. Un approbateur accepte ou refuse le brouillon enregistré.
8. Seul un brouillon accepté atteint le connecteur e-mail ou CRM de n8n.

Hermes ne doit pas disposer d’outils permettant l’envoi sur ce chemin. Le prompt peut préciser « ne pas envoyer », mais la suppression de cette capacité et le connecteur contrôlé de n8n sont les mesures qui résistent à une tentative de redirection de l’agent par du contenu non fiable.

Pour un résumé Slack interne qui ne revient pas dans n8n, utilisez plutôt l’interface webhook : configurez deliver: slack, signez l’événement, envoyez un X-Request-ID stable et interprétez la réponse de l’adaptateur uniquement comme un état de livraison.

Signature et décalage d’horloge

Pour le chemin webhook :

• Sérialisez le JSON une fois, signez exactement ces octets et envoyez exactement ces mêmes octets.
• Synchronisez les horloges de n8n et de Hermes ; une signature V2 valide par ailleurs, mais située hors de la fenêtre de 300 secondes, est refusée.
• La documentation officielle actuelle ne définit pas l’acceptation simultanée d’un ancien et d’un nouveau secret webhook. Utilisez un basculement contrôlé ou une procédure de rotation documentée pour la version déployée.
• Consignez les échecs de signature avec le nom de la route et un identifiant de corrélation non secret. Ne consignez jamais le secret.

Si n8n s’exécute dans Docker et Hermes sur l’hôte, utilisez une adresse stable et accessible depuis l’espace de noms réseau du processus n8n. Dans cette topologie, localhost désigne des espaces de noms différents.

Les rappels personnalisés constituent une intégration distincte

La documentation actuelle des webhooks Hermes ne répertorie aucune destination générique de rappel HTTP. Si votre déploiement en ajoute une au moyen de code personnalisé ou d’un outil, décrivez-la comme une intégration distincte et imposez-lui sa propre liste fixe de destinations autorisées, son authentification, sa validation de schéma, sa protection contre les SSRF, son idempotence durable et ses tests d’acceptation. Ne laissez pas entendre qu’un champ callback dans le corps du webhook entrant active une fonctionnalité intégrée à Hermes.

Aide-mémoire de décision

Ordre de construction minimal

Pour un chemin qui renvoie un résultat API :

1. Activez le serveur API sur l’interface de bouclage ou une interface privée et définissez API_SERVER_KEY.
2. Vérifiez l’accès authentifié à /v1/models et effectuez un appel d’essai à /v1/responses depuis le réseau d’exécution de n8n.
3. Ajoutez la validation du schéma de réponse et une clé applicative durable dans n8n.
4. Ajoutez la validation humaine avant tout connecteur visible par le client.
5. Testez les nouvelles tentatives à l’intérieur et à l’extérieur du cache API de cinq minutes.

Pour un chemin webhook événementiel :

1. Activez l’adaptateur webhook et configurez une route, un secret, un prompt restreint, des capacités limitées et une cible de diffusion.
2. Vérifiez /health et envoyez un événement d’essai signé en V2 depuis le réseau d’exécution de n8n.
3. Envoyez un X-Request-ID stable et examinez les états de livraison et de doublon de l’adaptateur.
4. Remplacez le déclencheur d’essai par l’événement réel validé et la clé durable n8n.
5. Testez les limites de débit et de taille du corps, la signature, l’horloge, la livraison et l’arrêt du service.

Tests d’acceptation avant le trafic de production

Pour l’interface API, conservez la preuve qu’une clé bearer absente ou incorrecte est refusée, qu’une requête d’essai renvoie le schéma attendu, qu’une nouvelle tentative immédiate avec le même Idempotency-Key ne provoque pas une deuxième exécution de l’agent, qu’une nouvelle tentative après le cache de cinq minutes reste bloquée ou est réconciliée par la clé applicative durable, que l’arrêt de Hermes produit un état d’attente visible et qu’un brouillon refusé n’atteint jamais un connecteur d’envoi.

Pour l’interface webhook, conservez la preuve qu’une requête non signée, un corps signé puis modifié et un horodatage hors de la fenêtre de 300 secondes sont refusés. Confirmez qu’un événement d’essai signé atteint la cible de diffusion configurée. Répétez l’envoi avec le même X-Request-ID dans l’heure et vérifiez qu’un état de doublon apparaît sans deuxième exécution ni deuxième livraison. Confirmez ensuite que les échecs liés à la limite de débit, à un corps trop volumineux, à une destination indisponible et à l’arrêt de Hermes sont visibles dans n8n.

L’intégration n’est prête pour un pilote qu’après la réussite des tests d’acceptation de l’interface concernée et l’attribution explicite des responsabilités. L’authentification par jeton bearer et la signature HMAC n’établissent l’identité de l’appelant que dans le cadre de leurs contrats documentés. Le cache API de cinq minutes et le cache d’ID de diffusion webhook d’une heure ne sont que des aides bornées aux nouvelles tentatives. L’idempotence applicative durable, l’autorisation, l’état d’approbation et la reprise métier restent sous la responsabilité de n8n ou du système métier.