Hermes-webhookit: tapahtumavetoiset agentit ilman valtavaa yleiskehotetta

Ajastus kysyy ”onko nyt aika?” Webhook sanoo ”tämä tapahtui juuri, toimi”. Ero on olennainen agenttityössä. Saapuneiden viestien ajastettu läpikäynti on eri tehtävä kuin reagointi siihen, että Stripe-riitautus luotiin tai pull request avattiin main-haaraa vastaan.

Hermes Agentin webhookit muuttavat todennetut HTTP POST -tapahtumat agenttiajoiksi, joiden tulokset lähetetään määritettyyn toimituskohteeseen. Hyvin toteutettuina ne ovat pieniä, lukittuja ovia, joilla jokaisella on selkeä tehtävä. Huonosti toteutettuina ne muodostavat avoimen portin ja yhden valtavan kehotteen, joka yrittää käsitellä jokaisen internetistä saapuvan JSON-hyötykuorman.

Tämä artikkeli käsittelee reittien suunnittelua, lähteeseen sopivaa todennusta, dokumentoitua terveystarkistusta ja käytännön perustestiä. Toteuta myös artikkelin /articles/hermes-first-week-memory-and-skills ensimmäisen viikon suojaustoimet ennen kuin avaat mitään paikalliskoneen ulkopuolelle.

Milloin webhookit ovat oikea laukaisin

Suosi webhookeja, kun:

• Viiveellä on merkitystä (tarkasta PR, kun tekijä on vielä keskittynyt samaan työhön).
• Lähdejärjestelmä jo lähettää tapahtumia (GitHub, GitLab, Jira, Stripe, sisäiset lomakkeet).
• Jokaisesta tapahtumasta pitäisi tulla yksi kohdennettu tehtävä, ei pitkä keskusteluistunto.

Suosi cronia, kun:

• Tarkistat ajastetusti muuttuvaa tilaa (”vanheneeko jokin varmenne 14 päivän sisällä?”).
• Lähde ei pysty työntämään tapahtumia.
• Haluat rauhallisen jaksottaisen koosteen tapahtumakohtaisten keskeytysten sijaan.

Virallinen Hermes-ohjeistus noudattaa samaa jakoa: cron ajastetuille tarkistuksille ja webhookit tapahtumien käynnistämille ajoille.

Arkkitehtuuri yhdessä kuvassa

Lähdejärjestelmä (GitHub / GitLab / n8n / mukautettu sovellus)
        |  HTTPS POST + lähteelle sopiva todennus
        v
Hermesin webhook-sovitin  (oletusportti 8644)
        |  reitti: /webhooks/<name>
        v
Nimetyn reitin määritys (suodattimet + kehote + toimitus)
        v
Agenttiajo (skills-paketit/työkalut hyväksyntäkäytäntösi mukaan)
        v
Määritetty toimitus (keskustelukanava, GitHub-kommentti tai loki)

n8n voi toimia kaavion vasemmalla puolella validointi- ja koontikerroksena: se tarkistaa kentät, poistaa tarpeettomat tiedot ja lähettää minimoidun hyötykuorman POST-pyynnöllä Hermekselle. Tämä on artikkelissa /articles/hermes-vs-n8n-choose-by-job kuvattu esimerkkiarkkitehtuuri, ei toimittajan dokumentoima valmis integraatio. Jos n8n tarvitsee agentin tuloksen takaisin työnkulkuunsa, kutsu erillistä Hermesin API-palvelinta oletusportissa 8642 Bearer-todennuksella. Älä käsittele webhook-sovitinta synkronisena paluukanavana.

Käyttöönottopolku (varmenna ajantasaisesta dokumentaatiosta)

Projektin alkuperäinen webhook-dokumentaatio kuvaa seuraavan polun:

1. Ota webhook-alusta käyttöön (hermes gateway setup tai ympäristömuuttuja kuten WEBHOOK_ENABLED=true).
2. Määritä jokaiselle reitille salaisuus. Käytä lähteen mukaan GitHubin HMAC-otsaketta, GitLabin selväkielistä token-otsaketta tai yleistä aikaleimallista V2-HMAC:ia.
3. Luo nimetty reitti konfiguraatiossa tai komennolla hermes webhook subscribe (komento nykyisen dokumentaation mukaan).
4. Health check: curl http://localhost:8644/health
5. Suuntaa ulkoinen järjestelmä osoitteeseen https://your-host/webhooks/<name>
6. Lähetä todennettu testihyötykuorma ja varmista odottamasi reitti, kehote, työkalujen laajuus ja toimituskohde.

Dokumentoitu oletusportti on 8644. Dokumentoidut oletusarvot rajoittavat reitin myös 30 pyyntöön minuutissa ja hylkäävät yli 1 MB:n pyynnöt. Jos muutat arvoja, testaa todelliset rajat oletusten sijaan.

Staattiset määritysmuutokset voivat edellyttää asennetun version dokumentoitua yhdyskäytävän elinkaarta. Komennolla hermes webhook subscribe luodut dynaamiset reitit latautuvat ilman uudelleenkäynnistystä ja saavat automaattisesti luodun salaisuuden. Varmista kummassakin tapauksessa, että yhdyskäytäväprosessi näkee tarkoitetun profiilin ja ympäristön; interaktiivisessa shellissä onnistunut komento ei todista taustaprosessin käyttävän samaa määritystä.

Reitin todennus ei ole valinnainen

Jokaisen reitin on perittävä tai määritettävä salaisuus, muuten sovitin ei käynnisty. Todennus on palveluntarjoajakohtaista: GitHub käyttää X-Hub-Signature-256-otsaketta, GitLab täsmällisesti vastaavaa X-Gitlab-Token-arvoa ja yleisten mukautettujen lähettäjien tulee käyttää aikaleimallista V2-HMAC:ia. Lähettäjän todennus osoittaa, että pyynnön lähetti salaisuuden haltija; se ei tee payloadin ohjeista luotettavia.

Säännöt, jotka kestävät tuotannossa:

• Luo pitkä satunnainen salaisuus ja säilytä se salaisuuksien hallintapalvelussa tai tiukoin oikeuksin suojatussa ympäristötiedostossa, ei koskaan agentin helposti luettavassa skill-Markdownissa.
• Suosi reittikohtaisia salaisuuksia, kun järjestelmillä on eri luottamustasot (GitHub-sovellus vs. sisäinen lomake vs. kumppanin webhook).
• Hylkää allekirjoittamattomat ja virheellisesti allekirjoitetut pyynnöt jo reunalla; älä sovella ”lokita ja jatka” -periaatetta.
• Käytä INSECURE_NO_AUTH-asetusta vain väliaikaisiin loopback-testeihin. Sovitin kieltäytyy käynnistymästä, jos arvo yhdistetään muuhun kuin loopback-bind-osoitteeseen, kuten 0.0.0.0 tai LAN-osoitteeseen.

Käytä omissa lähettäjissäsi Hermeksen nykyistä yleiskäyttöistä V2-skeemaa: X-Webhook-Timestamp on Unix-sekunteina; X-Webhook-Signature-V2 on pienaakkosinen heksadesimaalinen HMAC-SHA256-tiiviste merkkijonosta <timestamp>.<raw-body>. Hermes hylkää aikaleimat, jotka ovat ±300 sekunnin ikkunan ulkopuolella. V1 allekirjoittaa vain pyynnön rungon eikä siinä ole toistosuojausta, joten älä rakenna uusia lähettäjiä sen varaan (virallinen webhookien turvallisuussopimus).

Toistettava allekirjoitettu savutesti

Kun olet luonut reitin nimeltä support-triage, laita ei-arkaluontoinen hyötykuorma tiedostoon payload.json. Anna hyväksytyn salaisuuksien syöttömekanismin asettaa WEBHOOK_SECRET ennen tämän komentorivin käynnistymistä. Älä kirjoita tuotantosalaisuutta komentohistoriaan. Alla oleva Node-komento lukee avaimen ympäristöstä sen sijaan, että laajentaisi sen prosessin argumentteihin, ja allekirjoittaa täsmälleen tiedoston tavut:

: "${WEBHOOK_SECRET:?inject a disposable route secret before running this test}"
timestamp="$(date +%s)"
signature="$(TIMESTAMP="$timestamp" node -e '
  const { createHmac } = require("node:crypto");
  const { readFileSync } = require("node:fs");
  const hmac = createHmac("sha256", process.env.WEBHOOK_SECRET);
  hmac.update(`${process.env.TIMESTAMP}.`, "utf8");
  hmac.update(readFileSync("payload.json"));
  process.stdout.write(hmac.digest("hex"));
')"

curl --fail-with-body \
  -H 'Content-Type: application/json' \
  -H "X-Webhook-Timestamp: $timestamp" \
  -H "X-Webhook-Signature-V2: $signature" \
  --data-binary @payload.json \
  http://127.0.0.1:8644/webhooks/support-triage

Toista sen jälkeen sama ilman kumpaakaan allekirjoitusotsaketta ja yli 300 sekuntia vanhalla aikaleimalla. Molemmat on hylättävä. Älä liitä oikeaa salaisuutta kuvakaappauksiin, tiketteihin tai shell-historiaan; käytä dokumentaatiotesteissä kertakäyttöistä reittisalaisuutta ja kierrätä se testin jälkeen.

Altistettu webhook, joka voi syöttää hyökkääjän hallitsemaa tekstiä terminaalityökaluja käyttävälle agentille, aiheuttaa etätyökalujen suoritusvaaran. Todennus rajoittaa tapahtumien lähettäjiä, mutta myös todennetun payloadin teksti voi olla vihamielistä. Käytä TLS:ää ja verkkokontrolleja, minimoi payloadit, rajaa terminaali-, tiedosto- ja lähtevien toimintojen työkaluja tai poista ne käytöstä ja eristä suoritus hostista. Hyväksyntäpyynnöt suojaavat operaattorin aikomusta, eivät muodosta sandboxia vihamielistä syötettä vastaan.

Mitä laittaa payloadiin

Lähetä agentille sopimus, ei raakaa datavirtaa:

{
  "event_type": "github.pull_request.opened",
  "repo": "acme/api",
  "pr_number": 1842,
  "title": "Add billing retry worker",
  "author": "ada",
  "base_ref": "main",
  "html_url": "https://github.example.invalid/acme/agent-service/pull/1842",
  "task": "Summarize risk for main. List missing tests. Do not approve or merge."
}

Poista käyttämättömät kentät. Valtavat työnkulkuvedokset tuhlaavat kontekstia ja houkuttelevat sekavaan työkalukäyttöön. ”Pieni, täsmällinen hyötykuorma ja selkeä tehtävä” on tämän artikkelin suunnittelusuositus, ei väite virallisesta n8n-integraatiosta.

Reittien suunnittelu: monta pientä ovea

Älä rakenna reittiä /webhooks/everything. Rakenna nimettyjä reittejä suodattimineen ja kehotteineen:

Jokaisen reitin pitäisi vastata näihin:

1. Mitkä tapahtumat hyväksytään?
2. Mikä on se yksi odotettu tuotos?
3. Mitkä työkalut ovat sallittuja tämän reitin agenttiprofiilille?
4. Minne tulos menee?
5. Mitä tapahtuu virhetilanteessa: yritetäänkö uudelleen, siirretäänkö tapahtuma virhejonoon vai hälytetäänkö ihminen?

Webhook-payloadit sisältävät usein sähköpostiosoitteita, tilitunnuksia tai viestien sisältöä. Minimoi kentät ennen kuin ne saavuttavat Hermesin. Reittiskeema ei dokumentoi reittikohtaista muistikirjoituskytkintä. Käytä erillistä profiilia, jossa muisti on poistettu käytöstä tai memory.write_approval on käytössä, ja testaa, mitä säilyy. Jos agentin päättelyä ei tarvita, käytä dokumentoitua deliver_only-tilaa agenttiajon sijaan.

Terveystarkistukset ja operoitavuus

Dokumentoitu terveystarkistuksen päätepiste on http://localhost:8644/health (tai oma osoitteesi ja porttisi). Käytä sitä:

• Paikallisiin savutesteihin käyttöönoton jälkeen
• Dockerin ja Kubernetesin readiness-tarkistuksiin
• Ulkoisiin saatavuustarkistuksiin yksityistä terveystarkistusosoitetta vasten, ei todentamatonta webhook-reittiä vasten

Lokita myös:

• Allekirjoitusvirheet (mahdollinen hyökkäys tai väärin konfiguroitu salaisuus)
• Payloadin validointivirheet
• Agenttiajon kesto ja työkaluhyväksyntöjen epäämiset
• Alavirran toimitusvirheet (chat-rajapinta alhaalla ja niin edelleen)

Ilman näitä signaaleja ”agentti vaikutti epäluotettavalta” on ainoa häiriöraporttisi. Tiedot parantavat havaittavuutta, mutta eivät automaattisesti muodosta täydellistä ja väärentämisen kestävää auditointijälkeä.

Esimerkki: GitHub PR opened → kohdennettu ajo

Tavoite: Kun PR avataan main-haaraa vastaan, Hermes luonnostelee riskimuistiinpanon ihmisille. Se ei yhdistä, hyväksy eikä kommentoi, ellet myöhemmin lisää tarkistettua toimituspolkua.

1. Luo reitti gh-pr-opened. GitHubin suorassa toimituksessa määritä jaettu salaisuus X-Hub-Signature-256-otsakkeen tarkistamiseen; yleisessä n8n-välityksessä toteuta sen sijaan aikaleimallinen V2-HMAC-sopimus.
2. Suodata tapahtumiin pull_request / opened / base main.
3. Kehotesopimus: tiivistä tarkoitus, vaikutusalue, puuttuvat testit ja käyttöönottoriski; merkitse tuntemattomat; ei merge-ohjeita.
4. Työkalut: vain luettava GitHub-haku, jos se on määritetty; komentorivi pois käytöstä tai hyväksyntää vaativana.
5. Toimitus: postaa markdown sisäiseen kanavaan; ihminen päättää seuraavat askeleet.

Esimerkki hyvän agenttituloksen muodosta; mallisi sanamuoto vaihtelee:

PR #1842: Lisää laskutuksen uudelleenyritysprosessi (ada-haarasta main-haaraan)

Faktat
- Muuttaa laskutusprosessia ja jonon määritystä (annetun otsikon ja tiedostoluettelon perusteella).
- Linkitetty URL: `https://github.example.invalid/acme/agent-service/pull/1842` (esimerkki)

Riskit
- Uudelleenyritysten tulva, jos kasvava viive puuttuu [päätelmä; tarkista muutoksista]
- Otsikossa ei mainita idempotenssiavaimia [unclear]

Puuttuvat testit, jotka on vahvistettava
- Kaksoistoimitusten ja käsittelemättömien viestien käyttäytyminen
- Hälytys uudelleenyritysbudjetin täyttyessä

Älä yhdistä muutoksia tämän muistiinpanon perusteella. Ihmisen tarkistus vaaditaan.

Tuo on tapahtumavetoinen agenttiajo, jolla on pysäytyssääntö. Se ei ole itsenäinen koodinomistaja.

Harjoitus: suunnittele kolme reittiä ennen kuin otat yhdenkään käyttöön

Kirjoita paperille tai toimintaohjeeseesi kolme webhook-reittiä omalle tekniikkapinollesi. Täytä kustakin:

• Nimi
• Lähde + tapahtumasuodatin
• Todennustapa ja salaisuuden omistaja
• Hyötykuorman kentät: aloita enintään 10 kentästä tarkoituksellisen pienenä harjoitusbudjettina
• Kehote: aloita enintään 8 rivistä ja lisää sitten vain se, mitä reitin arvioinnit vaativat
• Sallitut työkalut
• Toimituskohde
• Virhekäyttäytyminen

Toteuta ensin vain pienimmän riskin reitti, tavallisesti sisäinen hälytys tai pelkän luonnoksen tuottava PR-yhteenveto. Aja curl /health-päätepistettä vasten, sitten todennettu testi-POST ja virheellisen todennuksen testi sekä lopuksi yksi oikea tapahtuma muussa kuin tuotantotietovarastossa tai testiprojektissa.

Odotettavissa olevat vikatilat

• Salaisuuden ristiriita kierrätyksen jälkeen: todennus epäonnistuu; korjaa yhdyskäytäväprosessin ympäristö, ei vain kannettavan komentoriviä.
• Liian laaja kehote: agentti improvisoi työkaluja; jaa reitti pienempiin.
• Uudelleenyritysmyrskyt: lähde toistaa POST-pyynnöt. Hermes säilyttää toimitustunnuksia välimuistissa tunnin, mutta toimiva deduplikointi edellyttää vakaata X-GitHub-Delivery- tai X-Request-ID-arvoa. Asiakkaalle näkyvät toimet tarvitsevat lisäksi kestävän liiketoimintaidempotenssin, jonka säilytysaika vastaa toistoikkunaa.
• Muistin saastuminen: suuren volyymin hälytykset päätyvät pysyvään muistiin; käytä erillistä profiilia ja täsmällisiä muistiasetuksia.
• Avoimeksi jäänyt portti: terveystarkistus ja webhookit ovat saavutettavissa ilman suunniteltuja TLS- ja verkkokontrolleja; suojaa verkko ennen työkalujen lisäämistä.

Viitteet, jotka kannattaa pitää auki

• Hermesin webhook-sovitin
• Hermesin API-palvelin
• Hermesin tietoturvamalli
• Hermes-dokumentaatio
• Sisäinen: /articles/first-ai-agent-in-n8n, /articles/hermes-vs-n8n-choose-by-job

Tapahtumapohjaiset agentit ansaitsevat paikkansa, kun jokainen reitti on rajattu, todennettu ja havaittavissa sekä sillä on määritetty toimituskohde. Webhook-sovitin on tapahtumien sisääntulon etuovi, ei bearer-todennettu pyyntö-vastaus-API. Suunnittele ja testaa se tämän eron mukaisesti.