I webhook hanno cambiato il modo in cui penso all’automazione degli agenti AI. Prima dei webhook, le mie automazioni erano basate sul tempo: controlla le nuove email ogni 5 minuti, controlla le notifiche di GitHub ogni 10 minuti, verifica lo stato del server ogni ora. Con i webhook, gli eventi vengono a me. Niente polling. Niente ritardi. Niente chiamate API sprecate a controllare quando nulla è cambiato.
La differenza è come controllare la tua cassetta della posta ogni 5 minuti rispetto ad avere un campanello che suona quando arriva posta. Uno è inefficiente e fastidioso. L’altro funziona e basta.
Cosa Fanno i Webhook per un Agente AI
Un webhook è un URL che riceve richieste HTTP POST quando si verifica un evento. GitHub può inviare un webhook quando viene aperto un PR. Stripe può inviare un webhook quando un pagamento fallisce. Il tuo sistema di monitoraggio può inviare un webhook quando un server va in panne.
OpenClaw può ricevere questi webhook e rispondere. La risposta non è solo “registralo” — è “comprendere cosa è successo e agire in modo intelligente.”
Webhook PR di GitHub → OpenClaw legge il PR, rivede il codice, pubblica un riepilogo e un feedback iniziale come commento. Questo avviene entro 30 secondi dall’apertura del PR. Con il polling, ci sarebbe un ritardo di 5-10 minuti.
Webhook di errore di pagamento → OpenClaw controlla la storia del cliente, elabora un’email appropriata (cliente esistente vs. nuovo cliente, primo errore vs. problema ricorrente), e la mette in coda per revisione. Tempo di risposta: meno di un minuto.
Webhook di avviso del server → OpenClaw controlla i log recenti del server interessato, identifica le cause probabili e pubblica una diagnosi preliminare nel canale Slack del team. Il team ottiene contesto insieme all’avviso, non solo “Il server X è giù.”
Impostare i Webhook
OpenClaw può ricevere webhook attraverso il suo endpoint API. La configurazione:
1. Configura OpenClaw per ascoltare i webhook su un endpoint specifico
2. Imposta il servizio esterno per inviare webhook a quell’endpoint
3. Scrivi le istruzioni di elaborazione nella configurazione del tuo agente: “Quando ricevi un webhook di GitHub con azione ‘aperto’ e tipo ‘pull_request’, rivedi il PR e pubblica un commento”
Il servizio esterno deve poter accedere alla tua istanza di OpenClaw, il che significa: il tuo server ha un URL pubblico (il più semplice), utilizzi un servizio di tunnel come ngrok o Tailscale (per configurazioni domestiche), oppure utilizzi un servizio di relay per webhook che mette in coda i webhook e li consegna quando il tuo agente si registra.
I Flussi di Lavoro che Ho Creato
Pipeline di notifica di distribuzione. Quando il codice viene unito in main (webhook di GitHub), OpenClaw:
1. Controlla se il CI è passato
2. Attiva la distribuzione se il CI è verde
3. Monitora la distribuzione per 5 minuti
4. Pubblica un aggiornamento dello stato su Slack con i cambiamenti distribuiti
5. Se qualcosa va storto, ripristina e avvisa il team
Questo ha sostituito un processo di distribuzione manuale che richiedeva 15 minuti di attenzione umana per ogni distribuzione. Ora non richiede alcuna attenzione umana per distribuzioni riuscite e circa 2 minuti per quelle fallite (ricontrollare l’avviso e decidere se il ripristino è stato sufficiente).
Triage del supporto clienti. Quando viene creato un ticket di supporto (webhook di help desk), OpenClaw:
1. Legge il contenuto del ticket
2. Controlla lo stato dell’account del cliente e la storia recente
3. Classifica il problema (fatturazione, tecnico, richiesta di funzionalità, altro)
4. Per problemi comuni: elabora una risposta
5. Per problemi complessi: assegna al membro del team giusto con contesto
6. Per problemi urgenti: invia una notifica immediata su Slack
Monitoraggio dei contenuti. Quando qualcuno menziona il nostro prodotto sui social media (webhook dello strumento di monitoraggio), OpenClaw:
1. Legge la menzione e valuta il sentiment
2. Menzioni positive: registra per la raccolta di prove sociali
3. Menzioni neutre: registra e salta
4. Menzioni negative: avvisa il team con contesto e risposta suggerita
Errori Comuni
Nessuna verifica della firma. I webhook sono richieste HTTP provenienti da Internet. Chiunque conosca l’URL del tuo endpoint può inviare webhook falsi. Verifica sempre le firme dei webhook: la maggior parte dei servizi firma i loro webhook con una chiave segreta. Rifiuta le richieste con firme non valide.
Nessuna idempotenza. I servizi webhook a volte inviano lo stesso evento due volte (ritrasmissioni di rete, riavvii del servizio). Il tuo gestore dovrebbe produrre lo stesso risultato che riceva un evento una volta o cinque volte. Includi un controllo: “Ho già elaborato l’evento con questo ID? Se sì, salta.”
Elaborazione lenta che blocca la risposta. Il servizio esterno si aspetta una risposta veloce (di solito entro 5-30 secondi). Se il tuo gestore impiega 2 minuti per elaborare l’evento, il servizio potrebbe scadere e riprovare, causando elaborazioni duplicate. Soluzione: rispondi immediatamente con uno stato 200, quindi elabora l’evento in modo asincrono.
Nessuna gestione degli errori per i fallimenti a valle. Il tuo gestore di webhook chiama un’API che è in panne. E ora? L’evento è perso a meno che tu non abbia implementato una logica di ritrasmissione o una coda di messaggi non recapitati per eventi falliti. Archivio tutti i payload dei webhook e li contrassegno come elaborati/non riusciti. Gli eventi falliti vengono riprovati automaticamente dopo 5 minuti, fino a 3 volte.
Quando Utilizzare Webhook vs. Polling
Utilizza i webhook quando: Il servizio esterno li supporta, hai bisogno di una risposta quasi in tempo reale e la frequenza degli eventi è irregolare (può essere 0 eventi all’ora o 50).
Utilizza il polling quando: Il servizio non supporta i webhook, stai aggregando dati nel tempo (controllando metriche, non rispondendo a eventi), oppure la tua infrastruttura non ha un endpoint pubblico.
In pratica, utilizzo i webhook per tutti i flussi di lavoro basati su eventi e il polling solo per i compiti di aggregazione dei dati. La combinazione copre tutto ciò di cui ho bisogno.
🕒 Published: