Hermes-webhooks: hændelsesdrevne AI-agenter uden én kæmpe universalprompt

Cron spørger »er det tid?« Webhooks siger »dette skete lige, så handl«. For arbejde med AI-agenter er forskellen væsentlig. En planlagt gennemgang af indbakken er noget andet end »der blev oprettet en Stripe-tvist« eller »der blev åbnet en pull request mod main«.

Hermes Agent-webhooks omsætter autentificerede HTTP POST-hændelser til agentkørsler, hvis resultater sendes til et konfigureret leveringsmål. Brugt rigtigt er de små døre med låse og klare opgaver. Brugt forkert er de en eksponeret port med én kæmpe prompt, der forsøger at håndtere enhver klump JSON, internettet sender.

Denne artikel dækker rutedesign, kildetilpasset autentificering, det dokumenterede sundhedstjek og en praktisk funktionstest. Kombinér den med hærdningen i Hermes Agent i den første uge, før du eksponerer noget ud over localhost.

Hvornår webhooks er den rigtige udløser

Foretræk webhooks, når:

• Kort svartid betyder noget, for eksempel når en pull request skal gennemgås, mens forfatteren stadig har sammenhængen i frisk erindring.
• Kildesystemet allerede udsender hændelser (GitHub, GitLab, Jira, Stripe, interne formularer).
• Hver hændelse bør blive til én fokuseret opgave, ikke en lang samtale.

Foretræk cron, når:

• Du kontrollerer regelmæssigt, om noget har ændret sig, for eksempel »udløber et certifikat om 14 dage?«.
• Kilden ikke selv kan sende hændelser.
• Du vil have en stille periodisk orientering frem for en afbrydelse for hver hændelse.

Den officielle Hermes-vejledning følger denne opdeling: cron til planlagte tjek og webhooks til hændelsesudløste kørsler.

Arkitektur i ét billede

Kildesystem (GitHub / GitLab / n8n / tilpasset app)
        |  HTTPS POST + autentificering tilpasset kilden
        v
Hermes-webhookadapter  (standardport 8644)
        |  rute: /webhooks/<name>
        v
Navngiven rutekonfiguration (filtre + prompt + levering)
        v
Agentkørsel (færdigheder/værktøjer under din godkendelsespolitik)
        v
Konfigureret levering (chatkanal, GitHub-kommentar eller log)

n8n kan ligge til venstre som et lag til validering og samling: Validér felter, fjern overflødigt indhold, og send derefter en minimeret nyttelast til Hermes med POST. Det er en illustrativ arkitektur i Hermes sammenlignet med n8n, ikke en dokumenteret nøglefærdig integration. Hvis n8n skal have agentresultatet tilbage i arbejdsgangen, skal du kalde den separate Hermes API-server på standardport 8642 med bearer-autentificering i stedet for at behandle webhookadapteren som et synkront tilbagekald.

Opsætningsforløb, som skal kontrolleres mod den aktuelle dokumentation

Den officielle webhookdokumentation beskriver dette forløb:

1. Aktivér webhookplatformen (hermes gateway setup eller en miljøvariabel som WEBHOOK_ENABLED=true).
2. Konfigurér en hemmelighed for hver rute. Brug GitHubs HMAC-header, GitLabs tokenheader i klartekst eller generel V2-HMAC med tidsstempel, alt efter kilden.
3. Opret en navngiven rute i konfigurationen eller via hermes webhook subscribe (kommandoen fremgår af den aktuelle dokumentation).
4. Sundhedstjek: curl http://localhost:8644/health
5. Peg det eksterne system på https://your-host/webhooks/<name>
6. Send en autentificeret testnyttelast; kontrollér den forventede rute, prompt, værktøjsafgrænsning og leveringsdestination.

Den dokumenterede standardport er 8644. Standardindstillingerne begrænser desuden en rute til 30 anmodninger pr. minut og afviser anmodningstekster over 1 MB. Hvis du har ændret værdierne, skal du teste de konfigurerede grænser i stedet for at stole på standarderne.

Ændringer i statisk konfiguration kan kræve den livscyklushåndtering af gatewayen, som din installerede version dokumenterer. Dynamiske ruter oprettet med hermes webhook subscribe genindlæses løbende uden genstart og får en automatisk genereret hemmelighed. I begge tilfælde skal du bekræfte, at gatewayprocessen ser den tilsigtede profil og det tilsigtede miljø. En vellykket kommando i en interaktiv shell beviser ikke, at baggrundsprocessen har samme konfiguration.

Ruteautentificering er obligatorisk

Hver rute skal arve eller definere en hemmelighed, ellers fejler adapteren ved opstart. Autentificeringen er leverandørspecifik: GitHub bruger X-Hub-Signature-256, GitLab kræver et nøjagtigt match i X-Gitlab-Token, og generelle brugerdefinerede afsendere bør bruge V2-HMAC med tidsstempel. Afsenderautentificering beviser, hvilken indehaver af hemmeligheden der sendte anmodningen; den gør ikke instruktioner i nyttelasten pålidelige.

Regler, der holder i produktion:

• Generér en lang tilfældig hemmelighed; gem den i et hemmelighedslager eller en miljøfil med begrænsede tilladelser, aldrig i en færdigheds Markdown-fil, som agenten uden videre kan læse.
• Foretræk en hemmelighed pr. rute, når systemer har forskellige tillidsniveauer (GitHub-app kontra intern formular kontra partnerwebhook).
• Afvis usignerede anmodninger og ugyldige signaturer ved netværksgrænsen. Log ikke blot fejlen for derefter at fortsætte.
• Brug kun INSECURE_NO_AUTH til en midlertidig test på loopback-grænsefladen. Adapteren nægter at starte, hvis værdien kombineres med binding til en anden adresse, for eksempel 0.0.0.0 eller en LAN-adresse.

Brug Hermes’ aktuelle generiske V2-metode til brugerdefinerede afsendere: X-Webhook-Timestamp er Unix-tid i sekunder; X-Webhook-Signature-V2 er HMAC-SHA256-kontrolsummen af <timestamp>.<raw-body> skrevet med små hexadecimale bogstaver. Hermes afviser tidsstempler uden for et vindue på ±300 sekunder. V1 signerer kun anmodningsteksten og mangler beskyttelse mod genafspilning, så byg ikke nye afsendere på den (officiel sikkerhedskontrakt for webhooks).

Reproducerbar signeret røgtest

Når du har oprettet ruten support-triage, lægger du en ikke-følsom nyttelast i payload.json. Lad den godkendte mekanisme til indsættelse af hemmeligheder angive WEBHOOK_SECRET, før denne shell startes; skriv ikke en produktionshemmelighed i kommandohistorikken. Node-kommandoen nedenfor læser nøglen fra miljøet i stedet for at udvide den i procesargumenterne og signerer filens nøjagtige bytes:

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

Gentag derefter uden nogen af de to signaturheadere og med et tidsstempel, der er ældre end 300 sekunder. Begge forsøg skal afvises. Indsæt aldrig en rigtig hemmelighed i skærmbilleder, supportsager eller shellhistorik; brug en midlertidig rutehemmelighed til dokumentationstest, og udskift den bagefter.

Et eksponeret webhook, som kan placere angriberstyret tekst foran en agent med terminaladgang, skaber risiko for ekstern værktøjsudførelse. Autentificering begrænser, hvem der kan indsende hændelser, men tekst i en autentificeret nyttelast kan stadig være fjendtlig. Brug TLS og netværkskontrol, minimér nyttelaster, afgræns eller deaktivér værktøjer til terminal, filer og udgående handlinger, og isolér kørslen fra værten. Godkendelsesprompts beskytter operatørens hensigt; de er ikke en sandkasse til fjendtlige input.

Hvad nyttelasten skal indeholde

Send agenten en kontrakt, ikke en ufiltreret 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."
}

Fjern ubrugte felter. Enorme udtræk af arbejdsgange spilder kontekst og indbyder til forvirret brug af værktøjer. ”Små, eksplicitte nyttelaster med en klar opgave” er denne artikels designanbefaling, ikke et krav om en officiel n8n-integration.

Rutedesign: mange små døre

Byg ikke /webhooks/everything. Byg navngivne ruter med filtre og prompts:

Hver rute bør besvare:

1. Hvilke hændelser accepteres?
2. Hvad er det ene forventede resultat?
3. Hvilke værktøjer er tilladt for denne rutes agentprofil?
4. Hvor går resultatet hen?
5. Hvad sker der ved fejl (nyt forsøg? fejlkø? tilkald et menneske?)?

Webhooknyttelaster indeholder ofte e-mailadresser, konto-id’er eller beskedtekst. Minimér felterne, før de når Hermes. Ruteskemaet dokumenterer ikke en særskilt indstilling for hukommelsesskrivning på hver rute. Brug en dedikeret profil med hukommelsen deaktiveret eller memory.write_approval aktiveret, og test, hvad der bevares. Hvis der ikke er brug for agentræsonnement, skal du bruge den dokumenterede deliver_only-tilstand i stedet for at køre en agent.

Sundhedstjek og drift

Dokumenteret sundhedsslutpunkt: http://localhost:8644/health (eller din vært/port). Brug det til:

• Lokale funktionstest efter aktivering
• Parathedstjek i Docker/Kubernetes
• Eksterne oppetidstjek mod en privat sundheds-URL, ikke mod en uautentificeret webhookrute

Log også:

• Signaturfejl (muligt angreb eller fejlkonfigureret hemmelighed)
• Fejl ved validering af nyttelast
• Agentkørslens varighed og afviste værktøjsgodkendelser
• Fejl i den efterfølgende levering, for eksempel når chat-API’et er utilgængeligt

Uden disse signaler bliver »agenten virkede ustabil« din eneste hændelsesrapport. Registreringerne forbedrer observerbarheden; de udgør ikke automatisk et komplet og manipulationssikkert revisionsspor.

Eksempel: GitHub-pull request åbnet → fokuseret kørsel

Mål: Når en pull request åbnes mod main, udarbejder Hermes en risikonote til mennesker. Den fletter, godkender eller kommenterer ikke, medmindre du senere tilføjer et gennemgået leveringsforløb.

1. Opret ruten gh-pr-opened. Ved direkte levering fra GitHub skal du konfigurere den delte hemmelighed, der bruges til at kontrollere X-Hub-Signature-256; ved et generelt n8n-relæ skal du i stedet implementere V2-HMAC-kontrakten med tidsstempel.
2. Filtrér til pull_request / opened / base main.
3. Promptkontrakt: Opsummér formål, konsekvensområde, manglende test og udrulningsrisiko; markér ukendte forhold; ingen instruktioner om sammenfletning.
4. Værktøjer: Skrivebeskyttet hentning fra GitHub, hvis den er konfigureret; shell er deaktiveret eller kræver godkendelse.
5. Levering: Send Markdown til en intern kanal; et menneske beslutter næste skridt.

Eksempel på formen af et godt agentsvar (illustrativ struktur: din models ordlyd vil variere):

PR #1842: Tilføj worker til nye faktureringsforsøg (ada til main)

Fakta
- Berører faktureringsworkeren og køkonfigurationen (ud fra den angivne titel og filliste).
- Linket URL: `https://github.example.invalid/acme/agent-service/pull/1842` (illustrativt)

Risici
- Storme af genforsøg, hvis stigende ventetid mangler [slutning; kontrollér i diffen]
- Titlen nævner ingen idempotensnøgler [unclear]

Test, der skal bekræftes
- Adfærd ved dobbeltlevering eller skadelige kømeddelelser
- Alarmering, når budgettet for nye forsøg er opbrugt

Flet ikke ud fra denne note. Menneskelig gennemgang er påkrævet.

Det er en hændelsesdrevet agentkørsel med en stopregel. Det er ikke en selvstændig kodeejer.

Øvelse: Design tre ruter, før du aktiverer én

Skriv på papir (eller i din driftsvejledning) tre webhookruter til din teknologistak. Udfyld følgende for hver rute:

• Navn
• Kilde + hændelsesfilter
• Autentificeringsmetode og hemmelighedsejer
• Felter i nyttelasten: Start med højst 10 som et bevidst lille øvelsesbudget
• Prompt: Start med højst 8 linjer, og tilføj derefter kun det, rutens evalueringer kræver
• Tilladte værktøjer
• Leveringsmål
• Fejladfærd

Implementér først ruten med den laveste risiko, typisk en intern alarm eller et pull request-resumé, der kun gemmes som kladde. Kør curl mod /health, derefter en autentificeret POST-test og en test med ugyldig autentificering og til sidst én rigtig hændelse i et kodelager uden for produktion eller et testprojekt.

Fejltilstande at forvente

• Uoverensstemmelse i hemmeligheden efter rotation: Autentificeringen fejler; ret det miljø, gatewayprocessen bruger, ikke kun shellmiljøet på din bærbare computer.
• For bred prompt: Agenten improviserer med værktøjer; del ruten op.
• En storm af genforsøg: Kilden gentager sine POST-anmodninger. Hermes gemmer leverings-id’er i en cache i én time, men meningsfuld deduplikering kræver et stabilt X-GitHub-Delivery eller X-Request-ID. Handlinger, som kunden kan se, kræver stadig varig forretningsmæssig idempotens med en opbevaringsperiode, der matcher genafspilningsvinduet.
• Forurening af hukommelsen: Store mængder alarmer når den varige hukommelse; brug en dedikeret profil og eksplicitte hukommelsesindstillinger.
• Eksponeret port: Sundhedstjek og webhooks kan nås uden den tilsigtede TLS og netværkskontrol; ret netværket, før du tilføjer værktøjer.

Referencer, der er værd at have åbne

• Hermes webhook adapter
• Hermes API-server
• Hermes sikkerhedsmodel
• Hermes dokumentation
• Internt: /articles/first-ai-agent-in-n8n, /articles/hermes-vs-n8n-choose-by-job

Hændelsesdrevne AI-agenter skaber værdi, når hver rute er snæver, autentificeret og observerbar og har et konfigureret leveringsmål. Webhookadapteren er indgangen til hændelser, ikke API’et med bearer-autentificering til anmodninger og svar. Design og test den derefter.