I webhooks hanno cambiato il mio modo di pensare all’automazione degli agenti IA. Prima dei webhooks, tutte le mie automazioni erano basate sul tempo: controllare le nuove e-mail ogni 5 minuti, esaminare le notifiche di GitHub ogni 10 minuti, interrogare lo stato del server ogni ora. Con i webhooks, gli eventi vengono a me. Nessuna interrogazione. Nessun ritardo. Nessun chiamata API sprecata per controllare quando nulla è cambiato.
La differenza è come controllare la tua cassetta della posta ogni 5 minuti contro avere un citofono che suona quando arriva la corrispondenza. Una è inefficace e noiosa. L’altra funziona semplicemente.
Cosa Fanno i Webhooks per un Aggente IA
Un webhook è un’URL che riceve richieste HTTP POST quando accade qualcosa. GitHub può inviare un webhook quando una PR viene aperta. Stripe può inviare un webhook quando un pagamento fallisce. Il tuo sistema di monitoraggio può inviare un webhook quando un server cade.
OpenClaw può ricevere questi webhooks e rispondere. La risposta non è solo “registrarlo” — è “capire cosa è successo e agire in modo intelligente.”
Webhook PR GitHub → OpenClaw legge la PR, esamina il codice, pubblica un riepilogo e commenti iniziali. Questo avviene entro 30 secondi dall’apertura della PR. Con l’interrogazione, ci sarebbe un ritardo di 5-10 minuti.
Webhook di pagamento fallito → OpenClaw controlla lo storico del cliente, redige un’e-mail appropriata (cliente esistente vs. nuovo cliente, primo fallimento vs. problema ricorrente), e la mette in attesa per revisione. Tempo di risposta: meno di un minuto.
Webhook di allerta server → OpenClaw controlla i log recenti del server interessato, identifica le cause probabili, e pubblica una diagnosi preliminare sul canale Slack del team. Il team riceve un contesto con l’allerta, non solo “Il Server X è caduto.”
Configurazione dei Webhooks
OpenClaw può ricevere webhooks tramite il suo endpoint API. La configurazione:
1. Configura OpenClaw per ascoltare i webhooks su un endpoint specifico
2. Configura il servizio esterno per inviare webhooks a questo endpoint
3. Scrivi istruzioni di gestione nella configurazione del tuo agente: “Quando ricevi un webhook GitHub con l’azione ‘aperta’ e il tipo ‘pull_request’, esamina la PR e pubblica un commento”
Il servizio esterno deve poter raggiungere la tua istanza OpenClaw, il che significa che o: il tuo server ha un’URL pubblica (la più semplice), o usi un servizio di tunneling come ngrok o Tailscale (per configurazioni domestiche), oppure usi un servizio di relè webhook che mette in coda i webhooks e li consegna quando il tuo agente si connette.
I Flussi di Lavoro che Ho Creato
Pipeline di notifica di deploy. Quando il codice viene fuso nel ramo principale (webhook GitHub), OpenClaw :
1. Controlla se CI è riuscito
2. Avvia il deploy se CI è verde
3. Monitora il deploy per 5 minuti
4. Pubblica un aggiornamento di stato su Slack con le modifiche rilasciate
5. Se qualcosa va male, torna indietro e avvisa il team
Questo ha sostituito un processo di deploy manuale che richiedeva 15 minuti di attenzione umana per ogni deploy. Adesso, richiede zero attenzione umana per i deploy riusciti e circa 2 minuti per i fallimenti (revisione dell’allerta e decisione se il rollback è stato sufficiente).
Smistamento del supporto clienti. Quando un ticket di supporto viene creato (webhook del servizio di assistenza), OpenClaw :
1. Legge il contenuto del ticket
2. Controlla lo stato dell’account cliente e il suo storico recente
3. Classifica il problema (fatturazione, tecnico, richiesta di funzionalità, altro)
4. Per i problemi comuni: redige una risposta
5. Per problemi complessi: assegna al giusto membro del team 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 sentimento
2. Menzioni positive: registra per la raccolta di prove sociali
3. Menzioni neutre: registra e prosegue
4. Menzioni negative: avvisa il team con contesto e risposta suggerita
Errore Comuni
Nessuna verifica della firma. I webhooks sono richieste HTTP provenienti da internet. Chiunque conosca il tuo URL di endpoint può inviare falsi webhooks. Controlla sempre le firme dei webhooks — la maggior parte dei servizi firma i propri webhooks con una chiave segreta. Rifiuta le richieste con firme non valide.
Nessuna idempotenza. I servizi di webhook a volte inviano lo stesso evento due volte (ritentativi di rete, riavvii del servizio). Il tuo gestore deve produrre lo stesso risultato, che riceva un evento una volta o cinque volte. Includi un controllo: “Ho già trattato l’evento con questo ID? Se sì, prosegui.”
Elaborazione lenta che blocca la risposta. Il servizio esterno si aspetta una risposta rapida (generalmente entro 5-30 secondi). Se il tuo gestore impiega 2 minuti a elaborare l’evento, il servizio potrebbe scadere e ritentare, causando un’elaborazione duplicata. Soluzione: rispondi immediatamente con uno stato 200, poi elabora l’evento in modo asincrono.
Nessuna gestione degli errori per i fallimenti a valle. Il tuo gestore webhook chiama un’API che è offline. E adesso? L’evento è perso a meno che tu non abbia implementato una logica di ritentativo o una coda di messaggi per gli eventi falliti. Io memorizzo tutti i payload dei webhook e li contrassegno come trattati/falliti. Gli eventi falliti vengono automaticamente ritentati dopo 5 minuti, fino a 3 volte.
Quando Usare Webhooks vs. Polling
Usa i webhooks 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 per ora o 50).
Usa il polling quando: il servizio non supporta i webhooks, stai aggregando dati nel tempo (controllo delle metriche, nessuna risposta agli eventi), o la tua infrastruttura non ha un endpoint pubblico.
In pratica, uso i webhooks per tutti i flussi di lavoro innescati da eventi e il polling solo per compiti di aggregazione dati. La combinazione copre tutto ciò di cui ho bisogno.
🕒 Published: