n8n → Hermes: välj ett API-anrop eller en händelsewebhook

n8n passar väl för förutsägbar automatisering: att ta emot en händelse, validera fält, anropa API:er, vänta på människor och skriva resultat. Hermes Agent är användbart när nästa steg kräver tolkning, exempelvis för att prioritera ett ärende utifrån språket, skriva ett svarsutkast, undersöka med verktyg eller avgöra vad ”brådskande” betyder i sammanhanget.

Det finns två rena mönster, och de har olika kontrakt. Om n8n behöver agentens resultat för att validera, lagra, godkänna eller skicka det, anropar du Hermes API-server. Om n8n skickar en händelse och Hermes ska leverera resultatet till ett konfigurerat mål i Slack, Telegram, GitHub, e-post eller någon annan stödd kanal, anropar du webhook-adaptern.

Använd den officiella dokumentationen för Hermes API-server, den officiella webhook-dokumentationen och NousResearchs kodarkiv. Här dokumenteras ingen särskild förstapartsnod för Hermes i n8n; n8n använder den generella noden HTTP Request.

En generisk n8n-avsändare ska använda Hermes V2-HMAC-kontrakt. Andra leverantörer kan ha adapterspecifik autentisering, till exempel GitHubs signatur eller GitLabs token. Varje rutt behöver sin dokumenterade hemlighet. INSECURE_NO_AUTH är endast för loopback-testning; nuvarande Hermes vägrar att starta det på en bindning som inte är loopback.

När du ska lämna över (och när inte)

Behåll i n8n

• Schemavalidering och maskering
• Idempotensnycklar och dubbletthantering (idempotens och mänskliga kontrollpunkter)
• Anslutningar till CRM, e-post och Slack med uttryckliga autentiseringsuppgifter
• Köer för mänskligt godkännande före extern sändning
• Cron- och webhook-utlösare

Lämna till Hermes

• Tvetydig klassificering som behöver kontext från dokument eller kodarkiv
• Flerstegsundersökning med verktyg i Hermes körmiljö och en godkänd förmågepolicy
• Utkast som ska använda beständigt minne eller skills
• Undersökningar i privata korpusar som agenten redan kan nå

Lämna inte över

• Ren if/then-dirigering du kan uttrycka i Switch-noder
• Loopar med stor volym och hög tokenförbrukning, som först bör gå genom en billigare klassificerare
• Hemligheter som n8n aldrig ska vidarebefordra, exempelvis token som klistras in i Hermes ”för enkelhetens skull”

Om hela uppgiften är agentbaserad och utlöses via chatt kan ett gatewaygränssnitt passa bättre. Se OpenClaw kontra Hermes utifrån jobbet. För en första n8n-agent utan Hermes, se första AI-agenten i n8n.

Välj kontraktet innan du bygger

Resultat som n8n behöver:
Händelse → n8n validerar + gör beständigt nyckelanspråk
         → HTTP Request (Bearer) → Hermes :8642/v1/responses eller /v1/runs
         → n8n validerar resultat → mänsklig kontrollpunkt → anslutning

Händelse som levereras av Hermes:
Händelse → n8n validerar + gör beständigt nyckelanspråk
         → HTTP Request (V2 HMAC) → Hermes :8644/webhooks/<name>
         → Hermes-agentkörning → konfigurerat leveransmål i Hermes

API-servern använder som standard 127.0.0.1:8642, kräver API_SERVER_KEY och exponerar de OpenAI-kompatibla ytorna /v1/chat/completions, /v1/responses och Runs API. Nyckeln ger åtkomst till Hermes fulla agentverktyg, inklusive terminal- och filåtgärder, så håll bindningen privat och den anropande parten strikt avgränsad.

Webhook-adaptern använder port 8644 som standard; dess hälsokontroll är http://localhost:8644/health, och rutterna ligger under /webhooks/<name>. En webhook-körning skickar resultatet till det deliver-mål som har konfigurerats för rutten. Den dokumenterade listan över mål omfattar chattplattformar, GitHub-kommentarer, e-post, Home Assistant och log. Den definierar inget generiskt mål för HTTP-callback.

n8n förblir ägare av beständigt tillstånd för SaaS-anslutningar och mänskliga kontrollpunkter. Hermes förblir det avgränsade resonemangssteget.

Kontraktet för webhookhändelser: litet och uttryckligt

Undvik att skicka hela n8n-trädet med objekt. Skicka ett uppgiftsobjekt som agenten kan agera på utan att gissa.

Illustrativt kontrakt:

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

Regler:

1. Ett förväntat utfall per rutt (eller en tydlig enum av utfall).
2. Behåll den beständiga applikationsnyckeln i n8n eller affärssystemet. Ett fält i nyttolasten kan användas för att koppla samman loggar, men Hermes behandlar det inte som webhookens dedupliceringsnyckel.
3. Skicka ett stabilt X-Request-ID för omförsök av samma överlämning. Hermes cachar webhookens leverans-ID i en timme och hoppar över en dubblettkörning eller leverans inom det fönstret.
4. Säg vad agenten inte får göra, till exempel skicka, återbetala eller radera.
5. Föredra utdrag framför fulla bilagor. Lagra blobs någon annanstans och skicka endast referenser som Hermes har behörighet att hämta.

Skapa en särskild Hermes-webhookrutt för varje arbetsflödesfamilj (support-triage, ops-alert) med egen prompt, egna filter, egen hemlighet, egna skills och egen leveranskonfiguration. Behandla varje fält i nyttolasten som obetrott innehåll. Kör agentmiljön i en sandlåda, begränsa promptmallen, ta bort onödiga verktyg och behåll godkännanden för destruktiva eller utgående åtgärder.

Exakt Hermes V2-HMAC-kontrakt

För en generisk n8n-avsändare anger den aktuella Hermes-dokumentationen V2:

• headern X-Webhook-Timestamp: Unix-sekunder;
• headern X-Webhook-Signature-V2: HMAC-SHA256 i gemener och hexadecimal form;
• signerade byte: <timestamp>.<raw-request-body>;
• skyddsfönster mot återuppspelning: tidsstämpeln måste ligga inom ±300 sekunder från Hermes klocka.

V1-formen X-Webhook-Signature, som bara signerar nyttolasten, är fortfarande kompatibel men saknar skydd mot återuppspelning. Använd den inte för nya arbetsflöden. Se säkerhetskontraktet uppströms.

Signeringsnod i n8n i egen drift

Lagra HERMES_WEBHOOK_SECRET endast i n8n-processens mekanism för hemligheter eller miljövariabler. Lägg den inte i en Set-nod eller incheckad JSON för arbetsflödet. I en Code-nod använder du den inbyggda Node-modulen crypto endast om din n8n-konfiguration tillåter modulen och nodens åtkomst till miljön:

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

För n8n i egen drift tillåter du endast den nödvändiga inbyggda modulen enligt den aktuella konfigurationen av moduler i Code-noden; aktivera inte godtyckliga externa moduler. Med externa Task Runners konfigurerar du NODE_FUNCTION_ALLOW_BUILTIN=crypto som en env-override i /etc/n8n-task-runners.json, inte bara i den primära n8n-containern. Åtkomst via $env beror också på N8N_BLOCK_ENV_ACCESS_IN_NODE. Om säkerhetspolicyn blockerar detta använder du en signeringstjänst som organisationen har godkänt eller en anpassad nod med stöd för hemligheter. Klistra inte in hemligheten i arbetsflödet.

Konfigurera följande HTTP Request-nod:

Välj inte HTTP-nodens strukturerade JSON-redigerare efter signeringen; ny serialisering kan ändra byten. Fallera stängt på allt annat än 2xx. Ett 200-svar kan betyda levererat eller dubblett beroende på rutt och leverans-ID; det är inget strukturerat agentresultat för n8n. Markera inte den beständiga n8n-nyckeln som completed bara för att Hermes accepterade eller levererade händelsen.

Använd den dokumenterade autentiseringen även för Hermes-webhooks som endast finns på LAN. Att tjänster finns i samma nätverk är inte autentisering. Nuvarande standardvärden begränsar dessutom varje webhook-rutt till 30 begäranden per minut, avvisar nyttolaster över 1 MB och cachar värden för X-Request-ID eller X-GitHub-Delivery i en timme. Det är tidsbegränsade transportkontroller, inte beständiga affärsgarantier.

Webhookens nyttolast innehåller ofta kundmeddelanden. Håll Hermes och n8n på privata nätverk eller ett kontrollerat och krypterat overlaynätverk. Föredra en lokal OpenAI-kompatibel bas-URL för Hermes när innehållet måste stanna inom den godkända gränsen; se lokala slutpunkter från n8n. HMAC autentiserar avsändaren, inte personerna som skapade verksamhetsfälten i nyttolasten.

Vad som returneras, och vem som skickar

Ytan avgör vem som tar emot resultatet.

A. Webhook-händelse med leverans som hanteras av Hermes

Rutten kör agenten och skickar svaret till det leveransmål som är konfigurerat i Hermes. n8n tar emot adapterstatus, inte agentens strukturerade svar. Använd detta när målet är Slack, Telegram, GitHub, e-post eller någon annan dokumenterad destination och inget senare n8n-steg behöver innehållet.

B. API-resultat returneras till n8n

Anropa POST http://127.0.0.1:8642/v1/responses med Authorization: Bearer <API_SERVER_KEY> när n8n måste ta emot svaret. Använd /v1/runs när agentsteget ska skickas in och observeras som en körning i stället för att hållas i en synkron HTTP-begäran. API:t använder loopback som standard, och dess bearer-nyckel krävs även där.

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

Efter anropet validerar n8n svarsschemat, kopplar resultatet till den beständiga applikationsnyckeln och öppnar den mänskliga kontrollpunkten. En fem minuter lång svarscache för Idempotency-Key i Hermes API kan göra omedelbara omförsök säkrare. Den ersätter inte n8n:s beständiga reservering, unikhetsbegränsning eller övergång av verksamhetstillstånd.

Feltyper

Använd Hermes MCP endast när Hermes verkligen behöver inspektera eller styra en n8n-yta. Ett HTTP-API-anrop eller en händelsewebhook är enklare när det är det faktiska kontraktet.

Exempel: supportformulär → Hermes API → mänsklig kontrollpunkt

Illustrativt normalflöde utan påståenden om driftsättning eller prestanda:

1. Webbplatsformulär POST:ar till n8n-webhook /support-intake.
2. n8n validerar e-postadress, meddelandelängd och källans enumvärde och reserverar sedan ticket-<uuid> beständigt.
3. n8n maskerar fält om policyn kräver det och bygger den avgränsade uppgiften.
4. HTTP Request anropar Hermes /v1/responses på port 8642 med bearer-autentiseringsuppgiften och en kortlivad Idempotency-Key.
5. Hermes returnerar agentresultatet till n8n.
6. n8n validerar obligatoriska fält och lagrar utkastet under den beständiga ärendenyckeln.
7. En godkännare accepterar eller avvisar det lagrade utkastet.
8. Endast ett accepterat utkast når n8n:s e-post- eller CRM-anslutning.

Hermes ska inte få verktyg med sändningsförmåga i det här flödet. Prompten kan säga ”skicka inte”, men det är den borttagna förmågan och n8n:s anslutning bakom en godkännandekontroll som står emot om obetrott innehåll försöker styra om agenten.

För en intern Slack-sammanfattning som inte ska tillbaka till n8n använder du webhook-ytan i stället: konfigurera deliver: slack, signera händelsen, skicka ett stabilt X-Request-ID och behandla adaptersvaret endast som leveransstatus.

Signering och klockavvikelse

För webhook-vägen:

• Serialisera JSON en gång, signera exakt dessa byte och skicka exakt dessa byte.
• Håll n8n:s och Hermes klockor synkroniserade; en annars giltig V2-signatur utanför 300-sekundersfönstret avvisas.
• Aktuell förstahandsdokumentation definierar inte samtidiga nuvarande och föregående webhook-hemligheter. Använd ett kontrollerat byte eller en dokumenterad rotationsprocedur för den version du driftsätter.
• Logga signaturfel med ruttnamn och en icke-hemlig korrelationsidentifierare. Logga aldrig hemligheten.

Om n8n körs i Docker och Hermes på värden använder du en stabil adress som kan dirigeras från n8n-processens nätverksnamnrymd. localhost syftar på olika namnrymder i den topologin.

Anpassade callback-anrop är en separat integration

Nuvarande Hermes-dokumentation för webhooks listar inget generiskt mål för HTTP-callback. Om din driftsättning lägger till ett sådant genom egen kod eller ett verktyg ska det beskrivas som en separat integration med en egen fast tillåtelselista för destinationer, autentisering, schemavalidering, SSRF-gräns, beständig idempotens och acceptanstester. Antyd inte att ett callback-fält i den inkommande webhookens nyttolast aktiverar en inbyggd Hermes-funktion.

Snabbguide för beslut

Minimal byggordning

För en API-resultatväg:

1. Aktivera API-servern på loopback eller ett privat gränssnitt och sätt API_SERVER_KEY.
2. Verifiera autentiserat /v1/models och ett enkelt /v1/responses-anrop från n8n-körmiljöns nätverk.
3. Lägg till validering av svarsschemat och en beständig applikationsnyckel i n8n.
4. Lägg till den mänskliga kontrollpunkten före varje kundsynlig anslutning.
5. Testa omförsök både inom och utanför API:ts femminuterscache.

För en händelsewebhook:

1. Aktivera webhook-adaptern och konfigurera en rutt, hemlighet, smal prompt, avgränsade förmågor och leveransmål.
2. Verifiera /health och en enkel V2-signerad händelse från n8n-körmiljöns nätverk.
3. Skicka ett stabilt X-Request-ID och granska adapterstatus för levererad respektive duplicerad händelse.
4. Ersätt testutlösaren med den verkliga validerade händelsen och beständiga n8n-nyckeln.
5. Testa fel för frekvens, nyttolastens storlek, signatur, klocka, leverans och stoppad tjänst.

Acceptanstester före produktionstrafik

För API-ytan behåller du belägg för att en saknad eller felaktig bearer-nyckel avvisas, att en enkel begäran returnerar det förväntade schemat, att ett omedelbart omförsök med samma Idempotency-Key inte skapar en andra agentkörning, att omförsök efter femminuterscachen fortfarande blockeras eller stäms av med den beständiga applikationsnyckeln, att stoppad Hermes ger ett synligt parkerat tillstånd och att ett avvisat utkast aldrig når en sändanslutning.

För webhook-ytan behåller du belägg för att en osignerad begäran, en ändrad signerad nyttolast och en tidsstämpel utanför 300-sekundersfönstret avvisas. Bekräfta att en signerad testhändelse når det konfigurerade leveransmålet. Upprepa med samma X-Request-ID inom en timme och verifiera dubblettstatus utan en andra agentkörning eller leverans. Bekräfta sedan att fel för frekvensbegränsning, för stor nyttolast, otillgängligt mål och stoppad Hermes är synliga i n8n.

Integrationen är redo för en pilot först när den relevanta ytan klarar sina acceptanstester och ägarskapet är uttryckligt. Bearer-autentisering och HMAC fastställer endast anroparens identitet inom sina dokumenterade kontrakt. API:ts femminuterscache och webhookens entimmescache för leverans-ID är tidsbegränsade hjälpmedel för omförsök. Beständig applikationsidempotens, auktorisering, godkännandetillstånd och affärsåterställning förblir n8n:s eller affärssystemets ansvar.