n8n → Hermes: valitse API-kutsu tai tapahtumawebhook tehtävän mukaan

n8n soveltuu ennakoitavaan automaatioon: tapahtumien vastaanottamiseen, kenttien tarkistamiseen, API-kutsuihin, ihmisen päätöksen odottamiseen ja tulosten kirjoittamiseen. Hermes Agent on hyödyllinen, kun seuraava vaihe vaatii tulkintaa, kuten viestin luokittelua, vastauksen luonnostelua, työkaluilla tehtävää selvitystä tai sen arviointia, mitä ”kiireellinen” tarkoittaa juuri tässä asiayhteydessä.

Selkeitä malleja on kaksi, ja niiden sopimukset ovat erilaiset. Jos n8n tarvitsee agentin tuloksen validoitavaksi, tallennettavaksi, hyväksyttäväksi tai lähetettäväksi, kutsu Hermesin API-palvelinta. Jos n8n lähettää tapahtuman ja Hermesin tulee toimittaa tulos määritettyyn Slack-, Telegram-, GitHub-, sähköposti- tai muuhun tuettuun kohteeseen, kutsu webhook-sovitinta.

Käytä Hermesin API-palvelimen virallista dokumentaatiota, webhookien virallista dokumentaatiota ja NousResearchin tietovarastoa. Virallinen projekti ei dokumentoi Hermesille omaa n8n-solmua, joten n8n käyttää yleiskäyttöistä HTTP Request -solmua.

Yleiskäyttöisen n8n-lähettäjän tulee käyttää Hermesin V2-HMAC-sopimusta. Muilla palveluntarjoajilla voi olla sovitinkohtainen todennus, kuten GitHubin allekirjoitus tai GitLabin tunniste. Jokainen reitti tarvitsee dokumentoidun salaisuuden. INSECURE_NO_AUTH on tarkoitettu vain loopback-testaukseen; nykyinen Hermes ei käynnisty tällä asetuksella muuhun kuin loopback-osoitteeseen sidottuna.

Milloin tehtävä siirretään Hermekselle ja milloin se pidetään n8n:ssä

Pidä n8n:ssä

• Skeeman validointi ja tietojen peittäminen
• Idempotenssiavaimet ja kaksoiskappaleiden poisto (idempotenssi ja ihmisen hyväksyntä)
• CRM-, sähköposti- ja Slack-liittimet täsmällisillä tunnuksilla
• Ihmisen hyväksyntäjonot ennen ulkoista lähetystä
• Ajastus- ja webhook-käynnistimet

Siirrä Hermekselle

• Monitulkintainen luokittelu, joka tarvitsee dokumentin tai tietovaraston kontekstia
• Monivaiheinen selvitys työkaluilla Hermesin ajoympäristössä ja hyväksytyn kyvykkyyskäytännön puitteissa
• Luonnostelu, jonka tulee käyttää pysyvää muistia tai Skills-paketteja
• Tutkimus yksityisissä aineistoissa, joihin agentilla on jo pääsy

Älä luovuta

• Puhdas if/then-reititys, jonka voi ilmaista Switch-solmuilla
• Suuren volyymin generointisilmukat, joiden edessä pitäisi käyttää halvempaa luokittelijaa
• Salaisuudet, joita n8n:n ei koskaan pitäisi välittää, kuten Hermekseen ”mukavuuden vuoksi” liitetyt käyttöoikeustunnukset

Jos koko tehtävä on agenttimainen ja käynnistyy chatista, yhdyskäytäväkäyttöliittymä voi olla parempi valinta. Katso OpenClaw vai Hermes tehtävän mukaan. Ensimmäisiin n8n-agentteihin ilman Hermestä voit tutustua artikkelissa ensimmäinen tekoälyagentti n8n:ssä.

Valitse sopimus ennen rakentamista

n8n tarvitsee tuloksen:
Tapahtuma → n8n validoi + varaa kestävän avaimen
      → HTTP Request (Bearer) → Hermes :8642/v1/responses tai /v1/runs
      → n8n validoi tuloksen → ihmisen hyväksyntä → liitin

Hermes toimittaa tapahtuman:
Tapahtuma → n8n validoi + varaa kestävän avaimen
      → HTTP Request (V2 HMAC) → Hermes :8644/webhooks/<name>
      → Hermes-agenttiajo → määritetty Hermes-toimituskohde

API-palvelin kuuntelee oletusarvoisesti osoitteessa 127.0.0.1:8642, vaatii API_SERVER_KEY-avaimen ja tarjoaa OpenAI-yhteensopivat reitit /v1/chat/completions ja /v1/responses sekä Runs API:n. Avain antaa pääsyn Hermesin koko agenttityökalukokonaisuuteen, mukaan lukien pääte- ja tiedostotoiminnot. Pidä sidontaosoite yksityisenä ja rajaa kutsujat tiukasti.

Webhook-sovittimen oletusportti on 8644. Sen terveystarkistus on http://localhost:8644/health, ja reitit sijaitsevat kohdassa /webhooks/<name>. Webhook-ajo lähettää tuloksen reitille määritettyyn deliver-kohteeseen. Dokumentoitu kohdeluettelo sisältää keskustelualustoja, GitHub-kommentit, sähköpostin, Home Assistantin ja arvon log. Se ei määritä yleiskäyttöistä HTTP-paluukutsun kohdetta.

n8n vastaa edelleen SaaS-liittimien ja ihmishyväksyntöjen kestävästä tilasta. Hermes pysyy rajattuna päättelyvaiheena.

Webhook-tapahtuman sopimus: pieni ja täsmällinen

Älä lähetä koko n8n-tietuepuuta. Lähetä tehtäväobjekti, jonka agentti voi käsitellä arvaamatta.

Havainnollistava sopimus:

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

Säännöt:

1. Yksi odotettu tulos reittiä kohden tai yksi selkeä tulosjoukko.
2. Pidä kestävä sovellusavain n8n:ssä tai liiketoimintajärjestelmässä. Pyynnön rungon kenttä voi yhdistää lokit, mutta Hermes ei käytä sitä webhookin kaksoiskappaleiden tunnistamiseen.
3. Lähetä sama vakaa X-Request-ID, kun samaa siirtoa yritetään uudelleen. Hermes säilyttää webhook-toimitustunnuksia välimuistissa tunnin ja ohittaa samana aikana saman tunnuksen uuden ajon tai toimituksen.
4. Kerro, mitä agentti ei saa tehdä, kuten lähettää, hyvittää tai poistaa.
5. Suosi otteita kokonaisten liitteiden sijaan. Säilytä suuret objektit muualla ja välitä vain viitteitä, jotka Hermes saa hakea.

Luo oma Hermes-webhook-reitti jokaiselle työnkulkuryhmälle (support-triage, ops-alert) ja anna sille oma kehote, suodattimet, salaisuus, Skills-paketit ja toimitusmääritys. Käsittele jokaista hyötykuorman kenttää epäluotettavana sisältönä. Eristä ajoympäristö, rajaa kehotemalli, poista tarpeettomat työkalut ja säilytä hyväksynnät tuhoaville tai ulospäin vaikuttaville toimille.

Hermesin täsmällinen V2-HMAC-sopimus

Nykyinen Hermes-dokumentaatio määrittää yleiselle n8n-lähettäjälle V2:n:

• otsake X-Webhook-Timestamp: Unix-sekunnit;
• otsake X-Webhook-Signature-V2: pienaakkosinen heksadesimaalinen HMAC-SHA256;
• allekirjoitettavat tavut: <timestamp>.<raw-request-body>;
• toiston estoikkuna: aikaleiman on oltava ±300 sekunnin sisällä Hermesin kellosta.

V1-muoto X-Webhook-Signature, joka kattaa vain pyynnön rungon, on edelleen yhteensopiva, mutta ei suojaa toistolta. Älä käytä sitä uusissa työnkuluissa. Katso virallinen tietoturvasopimus.

Allekirjoitussolmu itse ylläpidetyssä n8n:ssä

Säilytä HERMES_WEBHOOK_SECRET vain n8n-prosessin salaisuus- tai ympäristömekanismissa. Älä laita sitä Set-solmuun tai versionhallinnassa olevaan työnkulku-JSON:iin. Käytä Code-solmussa sisäänrakennettua Node-moduulia crypto vain, jos n8n-määrityksesi sallii moduulin ja solmun pääsyn ympäristöö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 } }];

Salli itsehostatussa n8n:ssä vain vaadittu sisäänrakennettu moduuli nykyisen Code-noden moduulimäärityksen mukaisesti. Älä ota mielivaltaisia ulkoisia moduuleja käyttöön. Määritä ulkoisia Task Runners -prosesseja käytettäessä NODE_FUNCTION_ALLOW_BUILTIN=crypto arvoksi env-override tiedostossa /etc/n8n-task-runners.json, ei vain n8n:n pääkontissa. $env-pääsy riippuu myös asetuksesta N8N_BLOCK_ENV_ACCESS_IN_NODE. Jos tietoturvakäytäntö estää pääsyn, käytä organisaation hyväksymää allekirjoituspalvelua tai salaisuusvarastoon liitettyä mukautettua nodea. Älä liitä salaisuutta työnkulkuun.

Määritä HTTP Request -solmu näin:

Älä valitse HTTP-noden rakenteista JSON-editoria allekirjoittamisen jälkeen; uusi sarjallistaminen voi muuttaa tavuja. Epäonnistu suljetusti muilla kuin 2xx-vastauksilla. Vastaus 200 voi tarkoittaa toimitusta tai kaksoiskappaletta reitistä ja toimitustunnuksesta riippuen; se ei ole n8n:lle tarkoitettu agentin rakenteinen tulos. Älä merkitse n8n:n kestävää avainta tilaan completed pelkästään siksi, että Hermes hyväksyi tai toimitti tapahtuman.

Käytä dokumentoitua todennusta myös vain LAN-verkossa oleville Hermes-webhookeille. Verkon paikallisuus ei ole todennus. Nykyiset oletukset rajoittavat webhook-reitin 30 pyyntöön minuutissa, hylkäävät yli 1 MB:n pyynnöt ja säilyttävät X-Request-ID- tai X-GitHub-Delivery-arvot välimuistissa tunnin. Ne ovat rajattuja siirron suojatoimia, eivät kestäviä liiketoimintatakuita.

Webhookin runko sisältää usein asiakkaiden viestejä. Pidä Hermes ja n8n yksityisissä verkoissa tai hallitussa salatussa verkkokerroksessa. Suosi Hermesille paikallista OpenAI-yhteensopivaa mallin perusosoitetta, kun sisällön on pysyttävä hyväksytyn rajan sisällä; katso paikalliset rajapinnat n8n:stä. HMAC todentaa lähettäjän, ei hyötykuorman liiketoimintakenttien laatineita henkilöitä.

Mitä palautetaan ja kuka lähettää

Valittu rajapinta ratkaisee tuloksen vastaanottajan.

A. Webhook-tapahtuma, jonka toimitusta Hermes hallitsee

Reitti ajaa agentin ja lähettää vastauksen määritettyyn Hermes-toimituskohteeseen. n8n saa sovittimen tilan, ei agentin rakenteista vastausta. Käytä tätä, kun kohteena on Slack, Telegram, GitHub, sähköposti tai muu dokumentoitu kohde eikä myöhempi n8n-vaihe tarvitse sisältöä.

B. API-tulos palautetaan n8n:lle

Kutsu POST http://127.0.0.1:8642/v1/responses otsakkeella Authorization: Bearer <API_SERVER_KEY>, kun n8n:n on saatava vastaus. Käytä reittiä /v1/runs, kun agenttivaihe tulee lähettää ja sitä tulee seurata ajona yhden synkronisen HTTP-pyynnön sijaan. API kuuntelee oletusarvoisesti loopbackissa, ja bearer-avain vaaditaan myös siellä.

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

Kutsun jälkeen n8n validoi vastausskeeman, liittää tuloksen kestävään sovellusavaimeen ja avaa ihmishyväksynnän. Hermesin API:n viiden minuutin Idempotency-Key-vastausvälimuisti voi tehdä välittömistä uudelleenyrityksistä turvallisempia. Se ei korvaa n8n:n kestävää varausta, yksikäsitteisyysrajoitetta eikä liiketoimintatilan siirtymää.

Vikatilat

Käytä Hermes MCP:tä vain, kun Hermesin on todella tarkasteltava tai hallittava n8n-rajapintaa. HTTP-API-kutsu tai tapahtumawebhook on yksinkertaisempi, kun se on varsinainen sopimus.

Esimerkki: tukilomake → Hermesin API → ihmishyväksyntä

Havainnollistava onnistunut polku ilman käyttöönotto- tai suorituskykyväitettä:

1. Verkkosivun lomake lähettää POST-pyynnön n8n-webhookiin /support-intake.
2. n8n validoi sähköpostin, viestin pituuden ja lähteen enum-arvon ja varaa sitten kestävästi arvon ticket-<uuid>.
3. n8n peittää kenttiä käytännön niin vaatiessa ja muodostaa rajatun tehtävän.
4. HTTP Request kutsuu Hermesin /v1/responses-reittiä portissa 8642 bearer-tunnuksella ja lyhytikäisellä Idempotency-Key-avaimella.
5. Hermes palauttaa agentin tuloksen n8n:lle.
6. n8n validoi vaaditut kentät ja tallentaa luonnoksen kestävän tukipyyntöavaimen alle.
7. Hyväksyjä hyväksyy tai hylkää tallennetun luonnoksen.
8. Vain hyväksytty luonnos pääsee n8n:n sähköposti- tai CRM-liittimeen.

Hermesillä ei pidä olla lähetyskykyisiä työkaluja tällä polulla. Kehote voi sanoa ”älä lähetä”, mutta toiminnon poistaminen ja n8n:n hyväksynnän taakse rajattu liitin ovat varsinaiset kontrollit. Ne suojaavat myös silloin, kun epäluotettava sisältö yrittää ohjata agenttia uudelleen.

Käytä sen sijaan webhook-rajapintaa sisäiseen Slack-yhteenvetoon, jota ei palauteta n8n:lle: määritä deliver: slack, allekirjoita tapahtuma, lähetä vakaa X-Request-ID ja käsittele sovittimen vastausta vain toimituksen tilana.

Allekirjoitus ja kellon poikkeama

Webhook-polulla:

• Sarjallista JSON kerran, allekirjoita täsmälleen nämä tavut ja lähetä täsmälleen samat tavut.
• Synkronoi n8n:n ja Hermesin kellot; muuten kelvollinen V2-allekirjoitus hylätään 300 sekunnin ikkunan ulkopuolella.
• Nykyinen virallinen dokumentaatio ei määritä vanhan ja uuden webhook-salaisuuden samanaikaista hyväksyntää. Käytä hallittua vaihtoa tai käyttöönotetulle versiolle dokumentoitua kierrätysmenettelyä.
• Kirjaa allekirjoitusvirheet reitin nimen ja ei-salaisen korrelaatiotunnuksen kanssa. Älä koskaan kirjaa salaisuutta.

Jos n8n toimii Dockerissa ja Hermes hostissa, käytä vakaata osoitetta, johon n8n-prosessin verkkoavaruus voi reitittää. Tässä topologiassa localhost viittaa eri verkkoavaruuksiin.

Mukautetut paluukutsut ovat erillinen integraatio

Nykyinen Hermesin webhook-dokumentaatio ei luettele yleiskäyttöistä HTTP-paluukutsun toimituskohdetta. Jos käyttöönotto lisää sellaisen mukautetulla koodilla tai työkalulla, kuvaa se erillisenä integraationa ja anna sille oma kiinteä sallittujen kohteiden luettelo, todennus, skeeman tarkistus, SSRF-raja, kestävä idempotenssi ja hyväksyntätestit. Älä anna ymmärtää, että saapuvan webhookin rungon callback-kenttä ottaa käyttöön Hermesin sisäänrakennetun ominaisuuden.

Päätöksen pikaopas

Pienin rakentamisjärjestys

API-tuloksen palauttavalle polulle:

1. Ota API-palvelin käyttöön loopbackissa tai yksityisessä rajapinnassa ja määritä API_SERVER_KEY.
2. Vahvista todennettu /v1/models ja yksi kokeellinen /v1/responses-kutsu n8n:n ajoympäristön verkosta.
3. Lisää vastausskeeman validointi ja kestävä n8n-sovellusavain.
4. Lisää ihmishyväksyntä ennen jokaista asiakkaalle näkyvää liitintä.
5. Testaa uudelleenyritykset API:n viiden minuutin välimuistin sisällä ja sen ulkopuolella.

Tapahtumawebhook-polulle:

1. Ota webhook-sovitin käyttöön ja määritä yksi reitti, salaisuus, rajattu kehote, rajatut kyvykkyydet ja toimituskohde.
2. Vahvista /health ja yksi V2-allekirjoitettu testitapahtuma n8n:n ajoympäristön verkosta.
3. Lähetä vakaa X-Request-ID ja tarkista sovittimen toimitus- ja kaksoiskappaletilat.
4. Korvaa testiliipaisin oikealla validoidulla tapahtumalla ja kestävällä n8n-avaimella.
5. Testaa pyyntömäärä, rungon koko, allekirjoitus, kello, toimitus ja pysäytetyn palvelun vikatilat.

Hyväksyntätestit ennen tuotantoliikennettä

Säilytä API-rajapinnasta todisteet siitä, että puuttuva tai väärä Bearer-avain hylätään, testipyyntö palauttaa odotetun skeeman, välitön uudelleenyritys samalla Idempotency-Key-arvolla ei luo toista agenttiajoa, viiden minuutin välimuistin jälkeen tehty uudelleenyritys estetään tai sovitetaan kestävällä sovellusavaimella, pysäytetty Hermes tuottaa näkyvän odotustilan ja hylätty luonnos ei koskaan pääse lähetysliittimeen.

Säilytä webhook-rajapinnasta todisteet siitä, että allekirjoittamaton pyyntö, allekirjoituksen jälkeen muutettu runko ja 300 sekunnin ikkunan ulkopuolinen aikaleima hylätään. Vahvista, että allekirjoitettu testitapahtuma saavuttaa määritetyn toimituskohteen. Toista se samalla X-Request-ID-arvolla tunnin sisällä ja tarkista kaksoiskappaletila ilman toista agenttiajoa tai toimitusta. Vahvista sitten, että nopeusrajan, liian suuren rungon, tavoittamattoman kohteen ja pysäytetyn Hermesin virheet näkyvät n8n:lle.

Integraatio on valmis pilottiin vasta, kun käytetty rajapinta läpäisee hyväksyntätestit ja vastuut ovat selkeät. Bearer- ja HMAC-todennus osoittavat kutsujan henkilöllisyyden vain dokumentoitujen sopimustensa puitteissa. API:n viiden minuutin välimuisti ja webhook-toimitustunnusten tunnin välimuisti ovat rajattuja uudelleenyrityksen apuja. Kestävä sovellusidempotenssi, valtuutus, hyväksyntätila ja liiketoiminnan palautuminen kuuluvat edelleen n8n:lle tai liiketoimintajärjestelmälle.