Webhooks — Der universelle Ereignis-Eingang | Easy Understand Hermes Agent

Webhooks — Der universelle Ereignis-Eingang

Stell dir das vor: Ein Entwickler eröffnet einen Pull Request auf GitHub, und innerhalb von Sekunden hat dein KI-Agent den Code bereits überprüft und einen Kommentar hinterlassen. Oder eine Zahlung auf Stripe schlägt fehl, und dein Agent benachrichtigt automatisch dein Team auf Telegram. Das ist die Magie von Webhooks — sie lassen externe Dienste an der Tür deines Agents klopfen und sagen: „Hey, gerade ist etwas passiert, bitte kümmer dich darum.“

Was sind Webhooks?

Webhooks sind wie eine Türklingel für deine Anwendungen. Statt ständig zu prüfen, ob sich etwas geändert hat (Polling), wartest du einfach darauf, dass die Klingel läutet. Wenn GitHub, GitLab, JIRA, Stripe oder irgendein anderer Dienst eine HTTP-POST-Anfrage an deinen Webhook-Endpunkt sendet, wacht dein Hermes-Agent auf, verarbeitet das Ereignis und wird aktiv.

Das Beste daran? Dein Agent kann auf viele Arten reagieren — Kommentare auf PRs posten, Nachrichten an Telegram oder Discord senden oder das Ergebnis einfach für eine spätere Überprüfung protokollieren.

Schnellstart

Der Einstieg ist überraschend einfach:

Aktiviere den Webhook-Adapter über hermes gateway setup oder Umgebungsvariablen
Definiere Routen in config.yaml oder erstelle sie dynamisch mit hermes webhook subscribe
Richte deinen Dienst auf http://your-server:8644/webhooks/<route-name> aus

Das war’s. Dein Agent ist jetzt im Bereitschaftsdienst.

Einrichtung des Gateways

Du hast zwei Möglichkeiten, Webhooks zu aktivieren — wähle, was dir angenehmer ist.

Option 1: Der Setup-Assistent

hermes gateway setup

Folge den Anweisungen, um Webhooks zu aktivieren, einen Port zu wählen und ein globales HMAC-Geheimnis festzulegen. Der Assistent übernimmt die gesamte langweilige Konfiguration für dich.

Option 2: Umgebungsvariablen

Füge diese Zeilen zu ~/.hermes/.env hinzu:

WEBHOOK_ENABLED=true
WEBHOOK_PORT=8644        # Standard
WEBHOOK_SECRET=your-global-secret

Sobald das Gateway läuft, überprüfe, ob es aktiv ist:

curl http://localhost:8644/health

Du solltest Folgendes sehen:

{"status": "ok", "platform": "webhook"}

Routen konfigurieren

Routen sind das Herzstück der Webhook-Verarbeitung. Jede Route sagt deinem Agenten, wie er mit Ereignissen aus einer bestimmten Quelle umgehen soll. Betrachte sie als personalisierte Anweisungen für verschiedene Arten von Besuchern.

Hier ist, was du pro Route konfigurieren kannst:

Eigenschaft	Was sie tut
`events`	Welche Ereignistypen akzeptiert werden (z. B. `["pull_request"]`). Leer lassen, um alles zu akzeptieren.
`secret`	HMAC-Geheimnis für die Signaturprüfung. Verwende `"INSECURE_NO_AUTH"` nur zum Testen.
`profile`	Welches Profil diese Route ausführen darf (nützlich bei Multiplexing).
`prompt`	Vorlagenzeichenfolge mit Punktnotation wie `{pull_request.title}`. Weglassen, um die vollständige JSON-Nutzlast auszugeben.
`filters`	Deklarative Bedingungen, um unerwünschte Nutzlasten zu ignorieren, bevor der Agent läuft.
`script`	Ein Filter-/Transformationsskript, das die Nutzlast vor der Vorlagenersetzung ändern kann.
`skills`	Welche Fähigkeiten für diesen Agentenlauf geladen werden sollen.
`toolsets`	Welche Werkzeuge der Agent verwenden kann (ersetzt das Standard-Webhook-Toolset).
`deliver`	Wohin die Antwort gesendet wird: `github_comment`, `telegram`, `discord`, `slack`, `log` und mehr.
`deliver_extra`	Zusätzliche Zustelldetails wie Repository-Name oder Chat-ID.
`deliver_only`	Den Agenten vollständig überspringen und die gerenderte Vorlage unverändert zustellen. Null LLM-Kosten!

Ein Praxisbeispiel

Schauen wir uns ein praktisches Setup an. Hier ist eine Route, die Pull Requests überprüft:

platforms:
  webhook:
    enabled: true
    extra:
      port: 8644
      secret: "global-fallback-secret"
      routes:
        github-pr:
          events: ["pull_request"]
          secret: "github-webhook-secret"
          prompt: |
            Review this pull request:
            Repository: {repository.full_name}
            PR #{number}: {pull_request.title}
            Author: {pull_request.user.login}
            URL: {pull_request.html_url}
            Diff URL: {pull_request.diff_url}
            Action: {action}
          skills: ["github-code-review"]
          deliver: "github_comment"
          deliver_extra:
            repo: "{repository.full_name}"
            pr_number: "{number}"

Und hier ist eine Route, die nur dann eine Telegram-Benachrichtigung sendet, wenn jemand in den Hauptzweig pusht:

        deploy-notify:
          events: ["push"]
          secret: "deploy-secret"
          prompt: "New push to {repository.full_name} branch {ref}: {head_commit.message}"
          filters:
            - field: "ref"
              equals: "refs/heads/main"
          deliver: "telegram"

Intelligente Filterung

Die filters-Funktion ist besonders praktisch. Anbieter senden oft eine Flut von Ereignissen, aber du interessierst dich nur für wenige. Filter ermöglichen es dir, das Rauschen zu ignorieren, bevor dein Agent überhaupt aufwacht. Nicht übereinstimmende Nutzlasten erhalten eine höfliche {"status":"ignored","reason":"filter"}-Antwort mit HTTP 200 — keine verschwendete Rechenleistung, keine unnötigen LLM-Aufrufe.

Direkter Zustellmodus

Hier ist ein raffinierter Trick: Setze deliver_only: true und dein Agent läuft überhaupt nicht. Die gerenderte Prompt-Vorlage wird zur wörtlichen Nachricht, die zugestellt wird. Das bedeutet Zustellung in unter einer Sekunde mit null LLM-Kosten. Perfekt für einfache Benachrichtigungen, die keine KI-Argumentation benötigen.

Sicherheitshinweis

Denk daran: Authentifiziert bedeutet nicht vertrauenswürdig. Nutzlastfelder von Webhooks sind nicht vertrauenswürdige Daten. Validiere und bereinige immer alles, was du in Prompts oder Vorlagen verwendest. Dein Agent sollte Webhook-Inhalte wie Benutzereingaben behandeln — mit gesunder Skepsis.

Das Fazit

Webhooks verwandeln deinen Hermes-Agenten in einen reaktionsfähigen Assistenten, der in Echtzeit auf die Welt reagiert. Ob du Code-Reviews automatisierst, Bereitstellungsbenachrichtigungen sendest oder komplexe ereignisgesteuerte Workflows aufbaust — der Webhook-Adapter macht all das mit nur wenigen Zeilen YAML möglich.