Webhooks — Ingresso Universale degli Eventi | Easy Understand Hermes Agent

Webhooks — Ingresso Universale degli Eventi

Immagina questo: uno sviluppatore apre una pull request su GitHub e, nel giro di pochi secondi, il tuo agente AI ha già esaminato il codice e pubblicato un commento. Oppure un pagamento fallisce su Stripe e il tuo agente notifica automaticamente il tuo team su Telegram. Questa è la magia dei webhook — permettono ai servizi esterni di bussare alla porta del tuo agente e dire: “Ehi, è appena successa una cosa, gestiscila tu.”

Cosa Sono i Webhook?

I webhook sono come un campanello per le tue applicazioni. Invece di controllare costantemente se qualcosa è cambiato (polling), aspetti semplicemente che il campanello suoni. Quando GitHub, GitLab, JIRA, Stripe o qualsiasi altro servizio invia una richiesta HTTP POST al tuo endpoint webhook, il tuo agente Hermes si sveglia, elabora l’evento e agisce.

La parte migliore? Il tuo agente può rispondere in molti modi — pubblicando commenti sulle PR, inviando messaggi su Telegram o Discord, o semplicemente registrando il risultato per una revisione successiva.

Avvio Rapido

Iniziare è sorprendentemente semplice:

Abilita l’adattatore webhook tramite hermes gateway setup o variabili d’ambiente
Definisci le route in config.yaml o creale dinamicamente con hermes webhook subscribe
Punta il tuo servizio a http://your-server:8644/webhooks/<nome-route>

Tutto qui. Il tuo agente è ora operativo.

Configurazione del Gateway

Hai due modi per abilitare i webhook, scegli quello che preferisci.

Opzione 1: La Procedura Guidata

hermes gateway setup

Segui le istruzioni per abilitare i webhook, scegliere una porta e impostare un segreto HMAC globale. La procedura gestisce tutta la configurazione noiosa per te.

Opzione 2: Variabili d’Ambiente

Aggiungi queste righe a ~/.hermes/.env:

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

Una volta che il gateway è in esecuzione, verifica che sia attivo:

curl http://localhost:8644/health

Dovresti vedere:

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

Configurazione delle Route

Le route sono il cuore della gestione dei webhook. Ogni route dice al tuo agente come gestire gli eventi da una fonte specifica. Pensale come istruzioni personalizzate per diversi tipi di visitatori.

Ecco cosa puoi configurare per ogni route:

Proprietà	A cosa serve
`events`	Quali tipi di eventi accettare (es. `["pull_request"]`). Lascia vuoto per accettare tutto.
`secret`	Segreto HMAC per la validazione della firma. Usa `"INSECURE_NO_AUTH"` solo per test.
`profile`	Quale profilo può eseguire questa route (utile con il multiplexing).
`prompt`	Stringa template con notazione a punti come `{pull_request.title}`. Ometti per scaricare l’intero payload JSON.
`filters`	Condizioni dichiarative per ignorare payload indesiderati prima che l’agente venga eseguito.
`script`	Uno script di filtro/trasformazione che può modificare il payload prima del templating.
`skills`	Quali skill caricare per questa esecuzione dell’agente.
`toolsets`	Quali strumenti l’agente può usare (sostituisce il toolset webhook predefinito).
`deliver`	Dove inviare la risposta: `github_comment`, `telegram`, `discord`, `slack`, `log` e altro.
`deliver_extra`	Dettagli aggiuntivi di consegna come nome repo o ID chat.
`deliver_only`	Salta completamente l’agente e consegna il prompt renderizzato così com’è. Zero costi LLM!

Un Esempio Reale

Diamo un’occhiata a una configurazione pratica. Ecco una route che esamina le pull request:

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

Ed ecco una route che invia una notifica Telegram solo quando qualcuno fa push sul branch principale:

        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"

Filtraggio Intelligente

La funzione filters è particolarmente utile. I provider inviano spesso un’ondata di eventi, ma a te interessano solo alcuni. I filtri ti permettono di ignorare il rumore prima ancora che il tuo agente si svegli. I payload che non corrispondono ricevono una cortese risposta {"status":"ignored","reason":"filter"} con HTTP 200 — nessun calcolo sprecato, nessuna chiamata LLM inutile.

Modalità di Consegna Diretta

Ecco un trucco intelligente: imposta deliver_only: true e il tuo agente non viene mai eseguito. Il template del prompt renderizzato diventa il messaggio letterale che viene consegnato. Questo significa consegna in meno di un secondo con zero costi LLM. Perfetto per notifiche semplici che non richiedono ragionamento AI.

Nota sulla Sicurezza

Ricorda: autenticato non significa affidabile. I campi del payload dei webhook sono dati non affidabili. Valida e sanifica sempre tutto ciò che usi nei prompt o nei template. Il tuo agente dovrebbe trattare il contenuto dei webhook come input utente — con sano scetticismo.

In Sintesi

I webhook trasformano il tuo agente Hermes in un assistente reattivo che risponde al mondo in tempo reale. Che tu stia automatizzando revisioni di codice, inviando notifiche di deploy o costruendo complessi flussi di lavoro basati su eventi, l’adattatore webhook rende tutto possibile con poche righe di YAML.