Webhooks i Hermes: händelsestyrda AI-agenter utan en enda enorm prompt

Cron frågar ”är det dags?”. En webhook säger ”det här hände nyss, agera”. Den skillnaden spelar roll i agentarbete. En schemalagd granskning av inkorgen är inte samma sak som ”en Stripe-tvist skapades” eller ”en pull request öppnades mot main”.

Webhooks i Hermes Agent omvandlar autentiserade HTTP POST-händelser till agentkörningar vars resultat skickas till ett konfigurerat leveransmål. Rätt använda fungerar de som små, låsta dörrar med tydliga uppgifter. Fel använda blir de en exponerad port och en enorm prompt som försöker hantera all JSON-data som internet skickar.

Den här artikeln behandlar utformning av rutter, autentisering som passar avsändaren, den dokumenterade hälsokontrollen och ett praktiskt grundtest. Kombinera den med första veckans härdning i /articles/hermes-first-week-memory-and-skills innan du exponerar något utanför localhost.

När webhooks är rätt utlösare

Föredra webhooks när:

• Svarstiden spelar roll, exempelvis när en PR ska granskas medan författaren fortfarande arbetar med den.
• Källsystemet redan skickar händelser, som GitHub, GitLab, Jira, Stripe eller interna formulär.
• Varje händelse ska bli en fokuserad uppgift, inte en lång konversationssession.

Föredra cron när:

• Du gör återkommande kontroller, exempelvis ”går något certifikat ut inom 14 dagar?”.
• Källan inte kan skicka händelser.
• Du vill ha en samlad återkommande rapport i stället för ett avbrott för varje händelse.

Officiell Hermes-vägledning matchar den här uppdelningen: cron för schemalagda kontroller och webhooks för händelseutlösta körningar.

Arkitektur i en bild

Källsystem (GitHub / GitLab / n8n / anpassad app)
        |  HTTPS POST + källanpassad autentisering
        v
Hermes webhookadapter  (standardport 8644)
        |  rutt: /webhooks/<name>
        v
Namngiven ruttkonfiguration (filter + prompt + leverans)
        v
Agentkörning (färdigheter/verktyg enligt din godkännandepolicy)
        v
Konfigurerad leverans (chattkanal, GitHub-kommentar eller logg)

n8n kan ligga före Hermes som ett lager för validering och sammanslagning: validera fälten, kasta ovidkommande data och skicka sedan en minimerad nyttolast till Hermes med POST. Det är en illustrativ arkitektur i /articles/hermes-vs-n8n-choose-by-job, inte en dokumenterad färdigintegration. Om n8n behöver få tillbaka agentresultatet i samma arbetsflöde anropar du den separata Hermes API-servern på standardport 8642 med bearer-autentisering. Behandla inte webhookadaptern som ett synkront återanrop.

Konfiguration (kontrollera mot aktuell dokumentation)

Hermes officiella webhookdokumentation beskriver den här vägen:

1. Aktivera webhookplattformen (hermes gateway setup eller en miljövariabel som WEBHOOK_ENABLED=true).
2. Konfigurera en hemlighet för varje rutt. Använd GitHubs HMAC-rubrik, GitLabs rubrik med klartexttoken eller generell tidsstämplad HMAC V2 beroende på källan.
3. Skapa en namngiven rutt i konfigurationen eller via hermes webhook subscribe (kommando enligt aktuell dokumentation).
4. Hälsokontroll: curl http://localhost:8644/health
5. Peka det externa systemet mot https://your-host/webhooks/<name>
6. Skicka en autentiserad testnyttolast och bekräfta att rutt, prompt, verktygsomfattning och leveransmål är de avsedda.

Den dokumenterade standardporten är 8644. Standardvärdena begränsar också en rutt till 30 förfrågningar per minut och avvisar begäranden med en kropp som är större än 1 MB. Om du har ändrat värdena ska du testa de konfigurerade gränserna i stället för att lita på standardvärdena.

Statiska konfigurationsändringar kan kräva att gatewayen hanteras enligt livscykeln som dokumenteras för den installerade versionen. Dynamiska rutter som skapas med hermes webhook subscribe läses in på nytt utan omstart och får en automatiskt genererad hemlighet. Bekräfta i båda fallen att gatewayprocessen använder rätt profil och miljö. Ett lyckat kommando i ett interaktivt skal bevisar inte att bakgrundsprocessen har samma konfiguration.

Rutt-autentisering är inte valfritt

Varje rutt måste ärva eller definiera en hemlighet, annars kan adaptern inte starta. Autentiseringen beror på avsändaren: GitHub använder X-Hub-Signature-256, GitLab använder en exakt matchande X-Gitlab-Token och generella avsändare bör använda tidsstämplad HMAC V2. Avsändarautentisering visar att förfrågan kom från någon som har hemligheten. Den gör inte instruktionerna i nyttolasten betrodda.

Regler som håller i produktion:

• Generera en lång slumpmässig hemlighet. Lagra den i en hemlighetshanterare eller en miljöfil med låsta behörigheter, aldrig i Markdown-filen för en färdighet där agenten enkelt kan läsa den.
• Använd helst en hemlighet per rutt när systemen har olika tillitsnivåer, exempelvis en GitHub-app, ett internt formulär och en partnerwebhook.
• Avvisa osignerade eller ogiltiga signaturer vid nätverksgränsen; ”logga och fortsätt” duger inte.
• Använd INSECURE_NO_AUTH endast för tillfällig loopback-testning. Adaptern vägrar starta om det värdet kombineras med en icke-loopback-bindning som 0.0.0.0 eller en LAN-adress.

Använd Hermes nuvarande generella V2-schema för anpassade avsändare: X-Webhook-Timestamp anges i Unix-sekunder och X-Webhook-Signature-V2 är HMAC-SHA256-kontrollsumman av <timestamp>.<raw-body> med hexadecimala gemener. Hermes avvisar tidsstämplar utanför ett fönster på ±300 sekunder. V1 signerar endast innehållet och saknar skydd mot återuppspelning, så bygg inte nya avsändare på den (officiellt säkerhetskontrakt för webhooks).

Reproducerbart test med signering

När du har skapat rutten support-triage lägger du en okänslig nyttolast i payload.json. Låt den godkända mekanismen för injicering av hemligheter sätta WEBHOOK_SECRET innan skalet startar. Skriv aldrig in en produktionshemlighet i kommandohistoriken. Node-kommandot nedan läser nyckeln från miljön i stället för att expandera den till processargumenten och signerar filens exakta byteföljd:

: "${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

Upprepa sedan utan något av signaturhuvudena och med en tidsstämpel som är äldre än 300 sekunder. Båda försöken måste avvisas. Klistra inte in en riktig hemlighet i skärmbilder, ärenden eller skalhistorik. Använd en hemlighet för engångsbruk vid dokumentationstester och rotera den efteråt.

En exponerad webhook som kan lägga angriparkontrollerad text framför en agent med terminalåtkomst skapar risk för fjärrstyrd verktygskörning. Autentisering begränsar vem som får skicka händelser, men även autentiserad nyttolast kan vara fientlig. Använd TLS och nätverkskontroller, minimera nyttolasten, begränsa eller inaktivera terminal- och filverktyg samt verktyg för externa åtgärder, och isolera körningen från värdsystemet. Godkännandedialoger är ett skydd för operatörens avsikt. De är ingen sandlåda för fientlig indata.

Vad du ska lägga i nyttolasten

Skicka agenten ett kontrakt, inte en ofiltrerad dataström:

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

Ta bort oanvända fält. Stora råutskrifter av arbetsflöden slösar kontext och leder lätt till förvirrad verktygsanvändning. ”Små, tydligt angivna nyttolaster med en klar uppgift” är den här artikelns designrekommendation, inte ett påstående om en officiell n8n-integration.

Ruttdesign: många små dörrar

Bygg inte /webhooks/everything. Bygg namngivna rutter med filter och avgränsade prompter:

Varje rutt ska svara på:

1. Vilka händelser accepteras?
2. Vad är den enda förväntade utdatan?
3. Vilka verktyg är tillåtna för den här ruttens agentprofil?
4. Vart går resultatet?
5. Vad händer vid fel, exempelvis omförsök, kö för misslyckade meddelanden eller larm till en människa?

Webhook-nyttolaster innehåller ofta e-postadresser, konto-ID:n eller meddelandetexter. Minimera fälten innan de når Hermes. Ruttschemat dokumenterar ingen inställning för minnesskrivning per rutt. Använd en särskild profil med inaktiverat minne eller memory.write_approval aktiverat, och testa vad som sparas. Om inget resonemang från en agent behövs ska du använda det dokumenterade deliver_only-läget i stället för att köra en agent.

Hälsokontroller och drift

Dokumenterad hälsoslutpunkt: http://localhost:8644/health (eller din värd och port). Använd den för:

• Lokala grundtester efter aktivering
• Beredskapskontroller i Docker/Kubernetes
• Externa tillgänglighetskontroller mot en privat URL för hälsokontroll, inte mot en oautentiserad webhook-rutt

Logga också:

• Signaturfel (möjlig attack eller felkonfigurerad hemlighet)
• Fel vid nyttolastvalidering
• Agentkörningens längd och nekade verktygsgodkännanden
• Nedströms leveransfel (chatt-API nere osv.)

Utan dessa signaler blir ”agenten fungerade ibland” din enda incidentrapport. Posterna förbättrar observerbarheten, men utgör inte automatiskt en fullständig och manipulationssäker revisionslogg.

Exempel: GitHub PR öppnad → fokuserad körning

Mål: När en PR öppnas mot main skriver Hermes ett riskutkast för människor. Den slår inte samman, godkänner eller kommenterar om du inte senare lägger till en granskad leveransväg.

1. Skapa rutten gh-pr-opened. För direkt leverans från GitHub konfigurerar du den delade hemligheten som används för att verifiera X-Hub-Signature-256. För ett generellt n8n-mellansteg implementerar du i stället det tidsstämplade HMAC V2-kontraktet.
2. Filtrera till pull_request / opened / bas main.
3. Promptkontrakt: sammanfatta syfte, påverkansområde, saknade tester och utrullningsrisk; markera okända uppgifter; ge inga instruktioner om sammanslagning.
4. Verktyg: skrivskyddad hämtning från GitHub om den är konfigurerad; skalet är inaktiverat eller kräver godkännande.
5. Leverans: posta markdown till en intern kanal; människa beslutar nästa steg.

Så här kan bra agentutdata se ut (illustrativ struktur: din modells formuleringar varierar):

PR #1842: Lägg till worker för nya faktureringsförsök (ada till main)

Fakta
- Berör faktureringsworkern och kökonfigurationen (utifrån angiven titel och fillista).
- Länkad URL: `https://github.example.invalid/acme/agent-service/pull/1842` (illustrativ)

Risker
- Stormar av nya försök om backoff saknas [inference; verify in diff]
- Titeln nämner inga idempotensnycklar [unclear]

Tester som behöver bekräftas
- Beteende vid dubblettleverans eller skadligt kömeddelande
- Larm när budgeten för nya försök är förbrukad

Slå inte samman utifrån den här anteckningen. Mänsklig granskning krävs.

Det är en händelsestyrd agentkörning med en stoppregel. Det är ingen autonom kodägare.

Övning: designa tre rutter innan du aktiverar en

Skriv tre webhookrutter för din tekniska miljö på papper eller i driftdokumentationen. Fyll i följande för varje rutt:

• Namn
• Källa + händelsefilter
• Autentiseringsmetod och ansvarig för hemligheten
• Nyttolastfält: börja med högst 10 som en medvetet liten övningsbudget
• Prompt: börja med högst 8 rader, lägg sedan endast till vad ruttens utvärderingar kräver
• Tillåtna verktyg
• Leveransmål
• Beteende vid fel

Börja med rutten med lägst risk, vanligtvis ett internt larm eller en PR-sammanfattning som endast är ett utkast. Kör curl mot /health, följt av en autentiserad test-POST, ett test med ogiltig autentisering och slutligen en verklig händelse i ett testförråd eller stagingprojekt.

Förväntade fel

• Fel hemlighet efter rotation: autentiseringen misslyckas. Rätta miljön som gatewayprocessen använder, inte bara skalet på din dator.
• Alltför bred prompt: agenten improviserar verktyg; dela rutten.
• Omförsöksstormar: källan skickar POST-begäranden på nytt. Hermes cachar leverans-ID:n i en timme, men meningsfull dubbletthantering kräver ett stabilt X-GitHub-Delivery eller X-Request-ID. Kundsynliga åtgärder behöver fortfarande beständig idempotens i verksamhetslogiken, med en lagringstid som motsvarar fönstret för återspelning.
• Minnesförorening: stora mängder larm skrivs in i beständigt minne; använd en särskild profil och tydliga minnesinställningar.
• Exponerad port: hälsokontrollen och webhookrutterna är nåbara utan avsedd TLS och avsedda nätverkskontroller; åtgärda nätverket innan du lägger till verktyg.

Referenser värda att ha öppna

• Hermes webhookadapter
• Hermes API server
• Hermes säkerhetsmodell
• Hermes dokumentation
• Internt: /articles/first-ai-agent-in-n8n, /articles/hermes-vs-n8n-choose-by-job

Händelsestyrda AI-agenter förtjänar sin plats när varje rutt är avgränsad, autentiserad och observerbar och har ett konfigurerat leveransmål. Webhookadaptern är en ingång för händelser, inte det bearer-autentiserade API:et för begäran och svar. Utforma och testa den därefter.