n8n → Hermes: vælg mellem et API-kald og en hændelseswebhook

n8n er stærk til forudsigelig automatisering: modtag en hændelse, validér felter, kald API’er, vent på mennesker, og gem resultater. Hermes Agent er nyttig, når næste trin kræver fortolkning, for eksempel sproglig triage, udarbejdelse af et svar, undersøgelse med værktøjer eller en kontekstafhængig vurdering af, hvad »akut« betyder.

Der er to klare mønstre med hver sin kontrakt. Hvis n8n skal bruge agentens resultat til at validere, gemme, godkende eller sende det, skal du kalde Hermes’ API-server. Hvis n8n udsender en hændelse, og Hermes skal levere resultatet til et konfigureret mål i Slack, Telegram, GitHub, e-mail eller en anden understøttet tjeneste, skal du kalde webhook-adapteren.

Brug den officielle dokumentation til Hermes’ API-server, den officielle webhook-dokumentation og NousResearch-repositoriet. Der er ikke dokumenteret en officiel Hermes-specifik n8n-node her; n8n bruger sin generiske HTTP Request-node.

En generisk n8n-afsender skal bruge Hermes’ V2 HMAC-kontrakt. Andre udbydere kan have adapterspecifik autentificering, for eksempel GitHubs signatur eller GitLabs token. Hver rute skal have sin dokumenterede hemmelighed. INSECURE_NO_AUTH er kun beregnet til test på loopback; den aktuelle Hermes-version nægter at starte med indstillingen på en binding uden for loopback.

Hvornår du skal overdrage (og hvornår ikke)

Behold i n8n

• Skemavalidering og maskering
• Idempotensnøgler og fjernelse af dubletter (idempotens og menneskelige kontrolpunkter)
• CRM/e-mail/Slack-konnektorer med eksplicitte legitimationsoplysninger
• Menneskelige godkendelseskøer før ekstern afsendelse
• Cron- og webhook-triggere

Overdr til Hermes

• Tvetydig klassifikation, der kræver kontekst fra dokumenter eller et versionslager
• Flertrinsundersøgelser med værktøjer under Hermes’ kørselsmiljø og den vedtagne kapacitetspolitik
• Udkast, der bør bruge vedvarende hukommelse eller færdigheder
• Undersøgelser i private tekstsamlinger, som agenten allerede har adgang til

Overdr ikke

• Ren hvis/så-dirigering, som kan udtrykkes med Switch-noder
• Høj-volumen genereringsløkker, der hører bag en billigere klassifikator først
• Hemmeligheder, som n8n aldrig bør videresende (indsæt tokens i Hermes »for bekvemmelighedens skyld«)

Hvis hele opgaven har form som agentarbejde og udløses via chat, kan en gateway-brugerflade være mere passende. Se OpenClaw og Hermes efter opgave. Hvis du bygger din første n8n-agent uden Hermes, kan du læse din første AI-agent i n8n.

Vælg kontrakten, før du bygger

Resultatet skal bruges af n8n:
Hændelse → n8n validerer + reserverer en varig nøgle
      → HTTP Request (Bearer) → Hermes :8642/v1/responses eller /v1/runs
      → n8n validerer resultatet → menneskelig godkendelse → connector

Hændelse leveret af Hermes:
Hændelse → n8n validerer + reserverer en varig nøgle
      → HTTP Request (V2 HMAC) → Hermes :8644/webhooks/<name>
      → Hermes-agentkørsel → konfigureret Hermes-leveringsmål

API-serveren lytter som standard på 127.0.0.1:8642, kræver API_SERVER_KEY og udstiller de OpenAI-kompatible slutpunkter /v1/chat/completions og /v1/responses samt Runs API. Nøglen giver adgang til hele Hermes’ værktøjssæt, herunder terminal- og filoperationer, så hold bindingen privat og begræns nøje, hvem der kan kalde den.

Webhookadapterens standardport er 8644; dens sundhedstjek er http://localhost:8644/health, og ruterne ligger under /webhooks/<name>. En webhookkørsel sender sit resultat til rutens konfigurerede deliver-mål. Den dokumenterede liste omfatter chatplatforme, GitHub-kommentarer, e-mail, Home Assistant og log. Den definerer ikke et generelt HTTP-callbackmål.

n8n forbliver ejer af den varige tilstand for SaaS-forbindelser og menneskelige godkendelser. Hermes forbliver det afgrænsede ræsonnementstrin.

Kontrakt for webhookhændelser: lille og tydelig

Undgå at dump hele n8n item-træet. Send et task-objekt, agenten kan handle på uden at gætte.

Illustrativ 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. Ét forventet resultat pr. rute eller én tydelig enum med mulige resultater.
2. Behold den varige applikationsnøgle i n8n eller forretningssystemet. Et felt i nyttelasten kan forbinde logposter, men Hermes behandler det ikke som sin nøgle til at fjerne dubletter fra webhooks.
3. Send et stabilt X-Request-ID ved nye forsøg på den samme overdragelse. Hermes cacher webhookleverings-id’er i én time og springer en dubletkørsel eller -levering over inden for dette vindue.
4. Sig, hvad agenten ikke skal gøre, såsom sende, refundere eller slette.
5. Foretræk uddrag frem for hele vedhæftede filer. Gem store filer andre steder, og send kun henvisninger, som Hermes har tilladelse til at hente.

Opret en dedikeret Hermes-webhookrute for hver familie af arbejdsgange (support-triage, ops-alert) med egen prompt, egne filtre, egen hemmelighed, egne skills og egen leveringskonfiguration. Behandl alle felter i nyttelasten som indhold, du ikke har tillid til. Kør kørselsmiljøet i en sandkasse, indsnævr promptskabelonen, fjern unødvendige værktøjer, og behold godkendelser for destruktive eller udgående handlinger.

Eksakt Hermes V2 HMAC-kontrakt

For en generel n8n-afsender angiver den aktuelle Hermes-dokumentation følgende V2-kontrakt:

• header X-Webhook-Timestamp: Unix sekunder;
• header X-Webhook-Signature-V2: HMAC-SHA256 med små hexadecimale bogstaver;
• signerede bytes: <timestamp>.<raw-request-body>;
• genafspilningsvindue: Tidsstemplet skal ligge inden for ±300 sekunder af Hermes’ ur.

V1-formen X-Webhook-Signature, som kun signerer anmodningens brødtekst, er fortsat kompatibel, men har ingen beskyttelse mod genafspilning. Brug den ikke til nye arbejdsgange. Se den officielle sikkerhedskontrakt.

Signeringsnode i egenhostet n8n

Gem kun HERMES_WEBHOOK_SECRET i n8n-processens mekanisme til hemmeligheder og miljøvariabler. Læg den ikke i en Set-node eller versionsstyret JSON for arbejdsgangen. Brug kun Nodes indbyggede crypto-modul i en Code-node, hvis n8n-konfigurationen tillader både modulet og nodens adgang til miljøet:

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

I egenhostet n8n skal du kun tillade det nødvendige indbyggede modul som beskrevet i den aktuelle konfiguration af moduler til Code-noden; tillad ikke vilkårlige eksterne moduler. Med eksterne Task Runners skal NODE_FUNCTION_ALLOW_BUILTIN=crypto konfigureres som en env-override i /etc/n8n-task-runners.json, ikke kun i den primære n8n-container. Adgang til $env afhænger også af N8N_BLOCK_ENV_ACCESS_IN_NODE. Hvis sikkerhedspolitikken blokerer dette, skal du bruge en organisationsgodkendt signeringstjeneste eller en brugerdefineret node med adgang til et hemmelighedslager. Indsæt ikke hemmeligheden i arbejdsgangen.

Konfigurér følgende HTTP Request-node:

Brug ikke HTTP-nodens strukturerede JSON-editor efter signeringen; ny serialisering kan ændre de signerede bytes. Afvis alle svar uden for 2xx. Et 200-svar kan betyde leveret eller dublet, afhængigt af ruten og leverings-id’et; det er ikke et struktureret agentresultat til n8n. Markér ikke den varige n8n-nøgle som completed, blot fordi Hermes accepterede eller leverede hændelsen.

Brug også den dokumenterede autentificering til Hermes-webhooks, der kun kan nås på lokalnettet. Netværksplacering er ikke autentificering. De aktuelle standardindstillinger begrænser desuden hver webhookrute til 30 anmodninger pr. minut, afviser brødtekster over 1 MB og gemmer værdierne i X-Request-ID eller X-GitHub-Delivery i en cache i én time. Det er begrænsede transportkontroller, ikke varige forretningsgarantier.

Webhookens anmodningsindhold omfatter ofte kundebeskeder. Hold Hermes og n8n på private netværk eller et kontrolleret krypteret overlaynetværk. Foretræk en lokal OpenAI-kompatibel grund-URL til Hermes-modellen, når indholdet skal blive inden for den godkendte grænse; se lokale slutpunkter fra n8n. HMAC autentificerer afsenderen, ikke de personer, der har skrevet forretningsfelterne i nyttelasten.

Hvad returnerer, og hvem sender

Overfladen bestemmer hvem modtager resultatet.

A. Webhook-begivenhed med Hermes-styret levering

Ruten kører agenten og sender svaret til det konfigurerede Hermes-leveringsmål. n8n modtager en adapterstatus, ikke agentens strukturerede svar. Brug dette, når Slack, Telegram, GitHub, e-mail eller et andet dokumenteret mål er destinationen, og ingen senere n8n-trin skal bruge indholdet.

B. API-resultat returneret til n8n

Kald POST http://127.0.0.1:8642/v1/responses med Authorization: Bearer <API_SERVER_KEY>, når n8n skal modtage svaret. Brug /v1/runs, når agenttrinnet skal indsendes og observeres som en kørsel frem for at blive holdt i én synkron HTTP-anmodning. API’et bruger loopback som standard, og bearer-nøglen er påkrævet selv dér.

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

Efter kaldet validerer n8n svarskemaet, knytter det til den varige applikationsnøgle og åbner den menneskelige godkendelse. Hermes-API’ets fem minutters svarcache for Idempotency-Key kan gøre umiddelbare gentagelser sikrere. Den erstatter ikke n8n’s varige reservation, entydighedsbegrænsning eller overgang i forretningstilstanden.

Fejltilstande

Brug kun Hermes MCP, når Hermes faktisk skal inspicere eller betjene en n8n-overflade. Et HTTP-API-kald eller en hændelseswebhook er enklere, når det er den reelle kontrakt.

Eksempel: supportformular → Hermes-API → menneskelig godkendelse

Illustrativt vellykket forløb uden påstand om udrulning eller ydeevne:

1. Webformularen sender en POST-anmodning til n8n-webhooken /support-intake.
2. n8n validerer e-mail, meddelelseslængde og kilde-enum og reserverer derefter ticket-<uuid> varigt.
3. n8n maskerer felter, hvis politikken kræver det, og opbygger den afgrænsede opgave.
4. HTTP Request kalder Hermes /v1/responses på port 8642 med bearer-legitimationsoplysninger og en kortlivet Idempotency-Key.
5. Hermes returnerer agentresultatet til n8n.
6. n8n validerer de krævede felter og gemmer udkastet under den holdbare ticket-nøgle.
7. En godkender accepterer eller afviser det gemte udkast.
8. Kun et accepteret udkast når n8n’s e-mail- eller CRM-connector.

Hermes bør ikke få værktøjer, der kan sende, på denne sti. Prompten kan sige “send ikke”, men fjernelse af kapaciteten og n8n’s godkendelsesbeskyttede forbindelsesnode er kontrollerne, der holder, hvis utroværdigt indhold forsøger at omdirigere agenten.

Brug webhook-overfladen til en intern Slack-opsummering, der ikke skal tilbage til n8n: konfigurér deliver: slack, signér hændelsen, send et stabilt X-Request-ID, og behandl kun adaptersvaret som leveringsstatus.

Signering og tidsafvigelse

For webhookstien:

• Serialisér JSON én gang, signér netop disse bytes, og send de samme bytes.
• Hold urene på n8n og Hermes synkroniserede; en ellers gyldig V2-signatur uden for vinduet på 300 sekunder afvises.
• Den aktuelle officielle dokumentation definerer ikke samtidig brug af en nuværende og en tidligere webhookhemmelighed. Brug et kontrolleret skift eller en dokumenteret rotationsprocedure til den installerede version.
• Log signaturfejl med rutens navn og en ikke-hemmelig korrelations-id. Log aldrig hemmeligheden.

Hvis n8n kører i Docker og Hermes på værten, skal du bruge en stabil adresse, der kan routes fra n8n-processens netværksnavnerum. localhost henviser til forskellige navnerum i denne topologi.

Brugerdefinerede callbacks er en separat integration

Den aktuelle Hermes-webhookdokumentation angiver ikke et generelt leveringsmål til HTTP-callbacks. Hvis din udrulning tilføjer et sådant mål via brugerdefineret kode eller et værktøj, skal du beskrive det som en separat integration med en fast tilladelsesliste over destinationer, autentificering, skemavalidering, SSRF-grænse, varig idempotens og accepttest. Antyd ikke, at et callback-felt i den indgående webhookbody aktiverer en indbygget Hermes-funktion.

Hurtig beslutningsoversigt

Minimal implementeringsrækkefølge

For en sti med API-resultat:

1. Aktivér API-serveren på loopback eller en privat grænseflade, og sæt API_SERVER_KEY.
2. Kontrollér et autentificeret kald til /v1/models og ét enkelt testkald til /v1/responses fra n8n-kørselsmiljøets netværk.
3. Tilføj validering af svarskemaet og en varig n8n-applikationsnøgle.
4. Tilføj den menneskelige godkendelse før enhver connector, som kunden kan se.
5. Test gentagelser både inden for og uden for API-cachen på fem minutter.

For en sti med hændelseswebhook:

1. Aktivér webhook-adapteren, og konfigurér én rute, hemmelighed, snæver prompt, afgrænsede funktioner og et leveringsmål.
2. Kontrollér /health og én enkel V2-signeret testhændelse fra n8n-kørselsmiljøets netværk.
3. Send et stabilt X-Request-ID, og undersøg adapterstatus for leveret og duplikeret.
4. Erstat testtriggeren med den rigtige validerede hændelse og en varig n8n-nøgle.
5. Test grænser for hastighed og kropsstørrelse samt fejl ved signatur, ur, levering og stoppet tjeneste.

Accepttest før produktionstrafik

Bevar for API-overfladen bevis for, at en manglende eller forkert bearer-nøgle afvises; at en enkel testanmodning returnerer det forventede skema; at en umiddelbar gentagelse med samme Idempotency-Key ikke skaber endnu en agentkørsel; at en gentagelse efter cachen på fem minutter stadig blokeres eller afstemmes af den varige applikationsnøgle; at en stoppet Hermes-tjeneste giver en synlig parkeret tilstand; og at et afvist udkast aldrig når en afsendelsesforbindelse.

Bevar for webhook-overfladen bevis for, at en usigneret anmodning, en ændret signeret krop og et tidsstempel uden for vinduet på 300 sekunder afvises. Bekræft, at en signeret testhændelse når det konfigurerede leveringsmål. Gentag med samme X-Request-ID inden for én time, og verificér en duplikatstatus uden endnu en agentkørsel eller levering. Bekræft derefter, at fejl ved hastighedsgrænse, for stor krop, utilgængeligt mål og stoppet Hermes er synlige for n8n.

Integrationen er først klar til en pilot, når den relevante overflade består sine accepttest, og ejerskabet er tydeligt. Bearer-godkendelse og HMAC fastslår kun kalderens identitet inden for deres dokumenterede kontrakter. API-cachen på fem minutter og webhookcachen for leverings-id’er på én time er begrænsede hjælpemidler ved gentagelser. Varig applikationsidempotens, autorisation, godkendelsesstatus og forretningsmæssig genopretning er fortsat n8n’s eller forretningssystemets ansvar.