n8n → Hermes: API-Aufruf oder Ereignis-Webhook wählen

n8n eignet sich für vorhersehbare Automatisierung: Ereignisse empfangen, Felder validieren, APIs aufrufen, auf menschliche Freigaben warten und Ergebnisse speichern. Hermes Agent ist sinnvoll, wenn der nächste Schritt eine inhaltliche Einordnung erfordert, etwa Sprache zu klassifizieren, eine Antwort zu entwerfen, mit Werkzeugen zu recherchieren oder im jeweiligen Kontext zu entscheiden, was „dringend“ bedeutet.

Es gibt zwei klare Muster mit unterschiedlichen Verträgen. Wenn n8n das Agentenergebnis validieren, speichern, freigeben oder versenden muss, rufen Sie den Hermes-API-Server auf. Wenn n8n ein Ereignis ausgibt und Hermes das Ergebnis an ein konfiguriertes Ziel wie Slack, Telegram, GitHub oder E-Mail zustellen soll, rufen Sie den Webhook-Adapter auf.

Verwenden Sie die offizielle Dokumentation des Hermes-API-Servers, die offizielle Webhook-Dokumentation und das NousResearch-Repository. Dort ist kein Hermes-spezifischer n8n-Knoten dokumentiert; n8n verwendet den allgemeinen Knoten HTTP Request.

Ein allgemeiner n8n-Sender sollte den Hermes V2 HMAC-Vertrag verwenden. Andere Anbieter können adapterspezifische Authentifizierungsverfahren nutzen, etwa die Signatur von GitHub oder das Token von GitLab. Jede Route benötigt das dafür dokumentierte Geheimnis. INSECURE_NO_AUTH ist ausschließlich für Tests über Loopback vorgesehen; die aktuelle Hermes-Version verweigert damit den Start, wenn sie nicht an eine Loopback-Adresse gebunden ist.

Wann übergeben (und wann nicht)

In n8n behalten

• Schemavalidierung und Schwärzung
• Idempotenzschlüssel und Deduplizierung (Idempotenz und menschliche Freigaben)
• CRM-, E-Mail- und Slack-Konnektoren mit ausdrücklich zugewiesenen Zugangsdaten
• Warteschlangen für die menschliche Freigabe vor einem externen Versand
• Cron- und Webhook-Trigger

An Hermes übergeben

• Mehrdeutige Klassifizierung, für die Dokument- oder Repository-Kontext erforderlich ist
• Mehrstufige Recherche mit Werkzeugen innerhalb der Hermes-Laufzeit und ihrer zugelassenen Berechtigungsrichtlinie
• Entwürfe, die einen dauerhaften Speicher oder Skills verwenden sollen
• Recherche in privaten Korpora, auf die der Agent bereits zugreifen darf

Nicht übergeben

• Reine Wenn-dann-Weiterleitung, die sich mit Switch-Knoten ausdrücken lässt
• Generierungsschleifen mit hohem Volumen, denen zunächst ein günstigerer Klassifikator vorgeschaltet werden sollte
• Geheimnisse, die n8n niemals weiterleiten sollte, etwa Tokens, die nur „der Bequemlichkeit halber“ in Hermes eingefügt werden

Wenn die gesamte Aufgabe einem Agenten entspricht und per Chat ausgelöst wird, ist möglicherweise eine Gateway-Oberfläche geeigneter. Vergleichen Sie dazu OpenClaw und Hermes nach Aufgabe. Für erste n8n-Agenten ohne Hermes lesen Sie Erster KI-Agent in n8n.

Wählen Sie den Vertrag, bevor Sie bauen

Ergebnis wird von n8n benötigt:
Ereignis → n8n validiert + reserviert dauerhaften Schlüssel
      → HTTP Request (Bearer) → Hermes :8642/v1/responses oder /v1/runs
      → n8n validiert Ergebnis → menschliche Freigabe → Konnektor

Ereignis wird von Hermes zugestellt:
Ereignis → n8n validiert + reserviert dauerhaften Schlüssel
      → HTTP Request (V2 HMAC) → Hermes :8644/webhooks/<name>
      → Hermes-Agentenlauf → konfiguriertes Hermes-Zustellungsziel

Der API-Server verwendet standardmäßig 127.0.0.1:8642, erfordert API_SERVER_KEY und stellt die OpenAI-kompatiblen Endpunkte /v1/chat/completions, /v1/responses sowie die Runs API bereit. Der Schlüssel gewährt Zugriff auf den gesamten Werkzeugsatz des Hermes-Agenten, einschließlich Terminal- und Dateioperationen. Halten Sie die Bindung privat und beschränken Sie die aufrufende Instanz eng.

Der Webhook-Adapter verwendet standardmäßig Port 8644. Sein Healthcheck ist http://localhost:8644/health; die Routen liegen unter /webhooks/<name>. Ein Webhook-Lauf sendet sein Ergebnis an das konfigurierte deliver-Ziel der Route. Die dokumentierte Zielliste umfasst Chatplattformen, GitHub-Kommentare, E-Mail, Home Assistant und log. Ein allgemeines HTTP-Callback-Ziel ist nicht definiert.

n8n bleibt für den dauerhaften Zustand der SaaS-Konnektoren und menschlichen Freigaben verantwortlich. Hermes bleibt der klar begrenzte Schritt für die inhaltliche Einordnung.

Webhook-Ereignisvertrag: klein und explizit

Übergeben Sie nicht den gesamten Elementbaum aus n8n. Senden Sie ein Aufgabenobjekt, das der Agent ohne Vermutungen verarbeiten kann.

Illustrativer Vertrag:

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

Regeln:

1. Ein erwartetes Ergebnis pro Route oder eine eindeutige Aufzählung möglicher Ergebnisse.
2. Verwalten Sie den dauerhaften Anwendungsschlüssel in n8n oder im Geschäftssystem. Ein Feld im Body kann Protokolle miteinander verknüpfen, aber Hermes behandelt es nicht als Schlüssel für die Webhook-Deduplizierung.
3. Senden Sie eine stabile X-Request-ID für Wiederholungen derselben Übergabe. Hermes zwischenspeichert Webhook-Zustellungs-IDs für eine Stunde und überspringt einen doppelten Lauf oder eine Zustellung innerhalb dieses Fensters.
4. Geben Sie an, was der Agent nicht tun darf, etwa senden, erstatten oder löschen.
5. Verwenden Sie vorzugsweise Auszüge statt vollständiger Anhänge. Speichern Sie Binärdateien an anderer Stelle und übergeben Sie nur Verweise, die Hermes abrufen darf.

Erstellen Sie für jede Workflow-Familie (support-triage, ops-alert) eine eigene Hermes-Webhook-Route mit eigenem Prompt, eigenen Filtern, einem eigenen Geheimnis, klar begrenzten Skills und einer eigenen Zustellkonfiguration. Behandeln Sie jedes Nutzdatenfeld als nicht vertrauenswürdigen Inhalt. Führen Sie die Laufzeit in einer Sandbox aus, begrenzen Sie die Prompt-Vorlage, entfernen Sie unnötige Werkzeuge und behalten Sie Freigaben für destruktive oder nach außen wirkende Aktionen bei.

Exakter Hermes V2 HMAC-Vertrag

Für einen allgemeinen n8n-Sender schreiben die aktuellen Hermes-Dokumente V2 vor:

• Header X-Webhook-Timestamp: Unix-Sekunden;
• Header X-Webhook-Signature-V2: HMAC-SHA256 als kleingeschriebene Hexadezimalzeichen;
• signierte Bytes: <timestamp>.<raw-request-body>;
• Schutzfenster gegen Wiederholungsangriffe: Der Zeitstempel darf höchstens ±300 Sekunden von der Hermes-Uhr abweichen.

Die nur über den Body gebildete V1-Signatur X-Webhook-Signature bleibt kompatibel, bietet jedoch keinen Schutz vor Wiederholungsangriffen. Verwenden Sie sie nicht für neue Workflows. Beachten Sie den Sicherheitsvertrag des Upstream-Projekts.

Signaturknoten für selbst gehostetes n8n

Speichern Sie HERMES_WEBHOOK_SECRET ausschließlich über den Geheimnis- oder Umgebungsmechanismus des n8n-Prozesses. Legen Sie es weder in einem Set-Knoten noch in einer eingecheckten Workflow-JSON-Datei ab. Verwenden Sie das integrierte Node-Modul crypto in einem Code-Knoten nur, wenn Ihre n8n-Konfiguration sowohl dieses Modul als auch den Umgebungszugriff des Knotens zulässt:

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

Erlauben Sie bei selbst gehostetem n8n gemäß der aktuellen Modulkonfiguration für Code-Knoten nur das erforderliche integrierte Modul; geben Sie keine beliebigen externen Module frei. Bei externen Task Runnern konfigurieren Sie NODE_FUNCTION_ALLOW_BUILTIN=crypto als env-override in /etc/n8n-task-runners.json, nicht nur im n8n-Hauptcontainer. Der Zugriff auf $env hängt außerdem von N8N_BLOCK_ENV_ACCESS_IN_NODE ab. Wenn Ihre Sicherheitsrichtlinie diesen Zugriff blockiert, verwenden Sie einen von Ihrer Organisation freigegebenen Signaturdienst oder einen benutzerdefinierten Knoten mit Geheimnisspeicher. Fügen Sie das Geheimnis nicht in den Workflow ein.

Konfigurieren Sie den folgenden HTTP Request-Knoten:

Verwenden Sie nach dem Signieren nicht den strukturierten JSON-Editor des HTTP-Knotens; eine erneute Serialisierung könnte die Bytes verändern. Brechen Sie bei einer Antwort außerhalb des 2xx-Bereichs sicher ab. Eine 200-Antwort kann je nach Route und Zustellungs-ID eine Zustellung oder ein Duplikat bedeuten; sie ist kein strukturiertes Agentenergebnis für n8n. Markieren Sie den dauerhaften n8n-Schlüssel nicht allein deshalb als completed, weil Hermes das Ereignis angenommen oder zugestellt hat.

Verwenden Sie auch für Hermes-Webhooks, die nur im LAN erreichbar sind, die dokumentierte Authentifizierung. Die Lage im lokalen Netzwerk ersetzt keine Authentifizierung. Die aktuellen Standardeinstellungen begrenzen jede Webhook-Route außerdem auf 30 Anfragen pro Minute, lehnen Bodies über 1 MB ab und speichern Werte von X-Request-ID oder X-GitHub-Delivery eine Stunde lang zwischen. Das sind begrenzte Transportkontrollen, keine dauerhaften geschäftlichen Garantien.

Der Webhook-Body enthält häufig Kundennachrichten. Betreiben Sie Hermes und n8n in privaten Netzwerken oder über einem kontrollierten verschlüsselten Overlay-Netz. Verwenden Sie für Hermes vorzugsweise eine lokale OpenAI-kompatible Basis-URL, wenn Inhalte innerhalb Ihrer freigegebenen Grenze bleiben müssen; siehe lokale Endpunkte aus n8n. HMAC authentifiziert den Absender, nicht die Personen, von denen die Geschäftsdaten in den Nutzdaten stammen.

Was zurückkommt, und wer sendet

Die Oberfläche bestimmt, wer das Ergebnis empfängt.

A. Webhook-Ereignis mit von Hermes verwalteter Zustellung

Die Route führt den Agenten aus und sendet seine Antwort an das konfigurierte Hermes-Zustellungsziel. n8n erhält einen Adapterstatus, nicht die strukturierte Antwort des Agenten. Verwenden Sie dieses Muster, wenn Slack, Telegram, GitHub, E-Mail oder ein anderes dokumentiertes Ziel die Ausgabe erhalten soll und kein späterer n8n-Schritt den Inhalt benötigt.

B. API-Ergebnis zurück an n8n

Rufen Sie POST http://127.0.0.1:8642/v1/responses mit Authorization: Bearer <API_SERVER_KEY> auf, wenn n8n die Antwort empfangen muss. Verwenden Sie /v1/runs, wenn der Agentenschritt als Lauf eingereicht und beobachtet werden soll, statt eine synchrone HTTP-Anfrage offen zu halten. Die API ist standardmäßig an Loopback gebunden; ihr Bearer-Schlüssel ist auch dort erforderlich.

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

Nach dem Aufruf validiert n8n das Antwortschema, ordnet es dem dauerhaften Anwendungsschlüssel zu und öffnet die menschliche Freigabe. Ein fünfminütiger Antwortcache für Idempotency-Key in der Hermes-API kann unmittelbare Wiederholungen sicherer machen. Er ersetzt weder die dauerhafte Reservierung in n8n noch eine Eindeutigkeitsbeschränkung oder den Übergang des Geschäftszustands.

Fehlermodi

Verwenden Sie Hermes MCP nur, wenn Hermes tatsächlich eine n8n-Oberfläche untersuchen oder bedienen muss. Ein HTTP-API-Aufruf oder ein Ereignis-Webhook ist einfacher, wenn genau darin der erforderliche Vertrag besteht.

Beispiel: Support-Formular → Hermes-API → menschliche Freigabe

Illustrativer Erfolgsablauf, ohne Aussage zu Deployment oder Leistung:

1. Das Websiteformular sendet per POST an den n8n-Webhook /support-intake.
2. n8n validiert E-Mail-Adresse, Nachrichtenlänge und Quellen-Enum und reserviert anschließend ticket-<uuid> dauerhaft.
3. n8n schwärzt Felder, sofern die Richtlinie dies verlangt, und erstellt die begrenzte Aufgabe.
4. HTTP Request ruft Hermes unter /v1/responses auf Port 8642 mit dem Bearer-Zugang und einem kurzlebigen Idempotency-Key auf.
5. Hermes gibt das Agentenergebnis an n8n zurück.
6. n8n validiert die erforderlichen Felder und speichert den Entwurf unter dem dauerhaften Ticket-Schlüssel.
7. Eine freigabeberechtigte Person nimmt den gespeicherten Entwurf an oder lehnt ihn ab.
8. Nur ein freigegebener Entwurf erreicht den E-Mail- oder CRM-Konnektor von n8n.

Hermes sollte für diesen Pfad keine Werkzeuge mit Versandberechtigung erhalten. Der Prompt kann „nicht senden“ vorgeben. Verlässlich verhindern jedoch erst die entfernte Berechtigung und der durch eine Freigabe geschützte n8n-Konnektor den Versand, wenn nicht vertrauenswürdiger Inhalt versucht, den Agenten umzuleiten.

Für eine interne Slack-Zusammenfassung, die nicht an n8n zurückkehrt, verwenden Sie stattdessen die Webhook-Oberfläche: Konfigurieren Sie deliver: slack, signieren Sie das Ereignis, senden Sie eine stabile X-Request-ID und behandeln Sie die Adapterantwort nur als Zustellstatus.

Signierung und Zeitabweichung

Für den Webhook-Pfad:

• Serialisieren Sie JSON einmal, signieren Sie genau diese Bytes und senden Sie genau diese Bytes.
• Halten Sie n8n- und Hermes-Uhren synchronisiert; eine ansonsten gültige V2-Signatur außerhalb des 300-Sekunden-Fensters wird abgelehnt.
• Die aktuellen Dokumente aus erster Hand definieren keine gleichzeitige Verwendung eines aktuellen und eines vorherigen Webhook-Geheimnisses. Nutzen Sie einen kontrollierten Wechsel oder ein für Ihre eingesetzte Version dokumentiertes Rotationsverfahren.
• Protokollieren Sie Signaturfehler mit dem Routennamen und einer nicht geheimen Korrelationskennung. Protokollieren Sie niemals das Geheimnis.

Wenn n8n in Docker und Hermes auf dem Host läuft, verwenden Sie eine stabile Adresse, die aus dem Netzwerk-Namespace des n8n-Prozesses erreichbar ist. localhost bezeichnet in dieser Topologie unterschiedliche Namespaces.

Benutzerdefinierte Callbacks sind eine separate Integration

Die aktuelle Hermes-Webhook-Dokumentation nennt kein allgemeines HTTP-Callback-Ziel für Zustellungen. Wenn Ihr Deployment ein solches Ziel über benutzerdefinierten Code oder ein Werkzeug ergänzt, beschreiben Sie es als separate Integration. Geben Sie ihm eine eigene feste Ziel-Allowlist, Authentifizierung, Schemavalidierung, SSRF-Grenze, dauerhafte Idempotenz und Akzeptanztests. Erwecken Sie nicht den Eindruck, ein callback-Feld in eingehenden Webhook-Nutzdaten aktiviere eine integrierte Hermes-Funktion.

Entscheidungshilfe

Minimale Reihenfolge für den Aufbau

Für einen API-Ergebnis-Pfad:

1. Aktivieren Sie den API-Server auf Loopback oder einer privaten Schnittstelle und setzen Sie API_SERVER_KEY.
2. Prüfen Sie einen authentifizierten Aufruf von /v1/models und einen einfachen Testaufruf von /v1/responses aus dem Laufzeitnetzwerk von n8n.
3. Ergänzen Sie die Validierung des Antwortschemas und einen dauerhaften n8n-Anwendungsschlüssel.
4. Fügen Sie vor jedem für Kunden sichtbaren Konnektor eine menschliche Freigabe ein.
5. Testen Sie Wiederholungen innerhalb und außerhalb des fünfminütigen API-Caches.

Für einen Ereignis-Webhook-Pfad:

1. Aktivieren Sie den Webhook-Adapter und konfigurieren Sie eine Route, ein Geheimnis, einen eng gefassten Prompt, begrenzte Fähigkeiten und ein Zustellungsziel.
2. Prüfen Sie /health und ein mit V2 signiertes Testereignis aus dem Laufzeitnetzwerk von n8n.
3. Senden Sie eine stabile X-Request-ID und prüfen Sie die Adapterstatus für zugestellte und doppelte Ereignisse.
4. Ersetzen Sie den Testauslöser durch das echte validierte Ereignis und den dauerhaften n8n-Schlüssel.
5. Testen Sie Ratenbegrenzung, Body-Größe, Signatur, Uhrzeit, Zustellung und Fehler bei gestopptem Dienst.

Akzeptanztests vor Produktivverkehr

Bewahren Sie für die API-Oberfläche Nachweise dafür auf, dass ein fehlender oder falscher Bearer-Schlüssel abgelehnt wird, eine Testanfrage das erwartete Schema zurückgibt und eine unmittelbare Wiederholung mit demselben Idempotency-Key keine zweite Agentenausführung erzeugt. Belegen Sie außerdem, dass eine Wiederholung nach Ablauf des fünfminütigen Caches weiterhin durch den dauerhaften Anwendungsschlüssel blockiert oder abgeglichen wird, ein Ausfall von Hermes zu einem sichtbaren Parkzustand führt und ein abgelehnter Entwurf niemals einen Versandkonnektor erreicht.

Bewahren Sie für die Webhook-Oberfläche Nachweise dafür auf, dass eine unsignierte Anfrage, ein veränderter signierter Body und ein Zeitstempel außerhalb des 300-Sekunden-Fensters abgelehnt werden. Bestätigen Sie, dass ein signiertes Testereignis das konfigurierte Zustellungsziel erreicht. Wiederholen Sie es innerhalb einer Stunde mit derselben X-Request-ID und prüfen Sie, dass ein Duplikatstatus ohne zweite Agentenausführung oder Zustellung erscheint. Bestätigen Sie anschließend, dass Ratenbegrenzung, ein zu großer Body, ein nicht verfügbares Ziel und Fehler bei gestopptem Hermes für n8n sichtbar sind.

Die Integration ist erst dann für einen Piloten bereit, wenn die betreffende Oberfläche ihre Akzeptanztests besteht und die Verantwortlichkeit eindeutig zugewiesen ist. Bearer-Authentifizierung und HMAC stellen die Identität des Aufrufers nur innerhalb ihrer dokumentierten Verträge fest. Der fünfminütige API-Cache und der einstündige Cache für Webhook-Zustellungs-IDs sind lediglich begrenzte Hilfen für Wiederholungen. Dauerhafte geschäftliche Idempotenz, Autorisierung, Freigabestatus und Wiederherstellung bleiben Aufgaben von n8n oder des Geschäftssystems.