Un webhook è una notifica HTTP automatica inviata da un sistema a un altro nel momento in cui si verifica un evento specifico. A differenza delle API tradizionali dove il client interroga periodicamente il server, con il webhook è il server a "chiamare" proattivamente il destinatario non appena qualcosa accade, in tempo reale e senza ritardi.
Cos'è un Webhook?
Il termine "webhook" combina "web" (il canale HTTP) e "hook" (aggancio, gancio): si tratta di un meccanismo che permette a un sistema di "agganciarsi" agli eventi di un altro sistema e ricevere notifiche automatiche. Tecnicamente, quando accade un evento predefinito (nuova prenotazione, pagamento ricevuto, ticket aperto), il sistema mittente invia una richiesta HTTP POST a un URL specificato in precedenza, incluso il payload JSON con i dettagli dell'evento.
I webhook sono fondamentali nell'ecosistema dei chatbot aziendali: permettono al bot di sapere immediatamente quando una conversazione richiede follow-up, quando un handoff a operatore è stato completato, quando una prenotazione è stata confermata dal sistema esterno, o quando i dati di un cliente nel CRM sono cambiati e il bot deve aggiornare le proprie informazioni.
Webhook vs Polling: Confronto
Polling (Metodo Tradizionale)
Il client chiama periodicamente l'API per verificare se ci sono aggiornamenti, indipendentemente dal fatto che siano avvenute modifiche.
- Chiamate inutili quando non ci sono eventi
- Ritardo pari all'intervallo di polling (es. 1 minuto)
- Spreco di risorse server e banda
- Difficile scalare con molti client
Esempio: controlla ogni 30 secondi se c'è un nuovo ordine → 99,9% delle chiamate restituisce "niente di nuovo"
Webhook (Metodo Moderno)
Il server notifica proattivamente il client non appena l'evento accade. Niente chiamate inutili, notifica istantanea.
- Zero chiamate inutili, solo eventi reali
- Notifica in millisecondi dall'evento
- Efficiente in termini di risorse
- Scala bene anche con migliaia di client
Esempio: non appena arriva un ordine, il sistema invia immediatamente la notifica all'endpoint configurato
Come Funziona un Webhook
Step 1: Configurazione
Nel pannello del sistema mittente (CRM, piattaforma ecommerce, sistema di pagamento), si configura il webhook specificando: l'URL dell'endpoint destinatario (es.https://tuodominio.com/webhooks/ordini), gli eventi da notificare (es. "nuovo ordine", "pagamento ricevuto", "ordine spedito"), e la chiave segreta per la firma HMAC.
Step 2: Evento e Invio Notifica
Quando l'evento si verifica nel sistema mittente, questo costruisce un payload JSON con i dettagli dell'evento, calcola la firma HMAC del payload con la chiave segreta condivisa, e invia una richiesta HTTP POST all'endpoint configurato con payload e firma nell'header.
Step 3: Ricezione e Verifica
Il sistema ricevente (es. il backend del chatbot) verifica la firma HMAC ricalcolandola con la chiave segreta e confrontandola con quella ricevuta nell'header. Se le firme coincidono, il payload è autentico e può essere elaborato. Se non coincidono, la richiesta viene rifiutata (possibile tentativo di attacco o errore di configurazione).
Step 4: Risposta e Retry
Il ricevente deve rispondere con HTTP 200 il prima possibile (entro 5-30 secondi, a seconda del mittente). Elaborazioni lunghe vanno fatte in modo asincrono. Se il destinatario non risponde o risponde con un codice di errore (5xx), il mittente riprova automaticamente dopo un intervallo crescente (retry con exponential backoff), tipicamente 3-10 volte nell'arco di alcune ore.
Sicurezza dei Webhook
Firma HMAC: Il Metodo Standard
HMAC (Hash-based Message Authentication Code) garantisce che il webhook provenga effettivamente dal sistema autorizzato. Il mittente calcola:HMAC-SHA256(payload, chiave_segreta). Il ricevente ricalcola la firma e confronta. Se coincidono: autentico. Se no: rigettato.
La chiave segreta non viene mai trasmessa nella richiesta, solo la firma. È impossibile ricavare la chiave dalla firma (funzione unidirezionale).
Idempotency: Prevenire Elaborazioni Doppie
Il sistema mittente può inviare lo stesso webhook più volte (in caso di timeout o errori di rete). È fondamentale che il ricevente gestisca i duplicati: ogni evento ha un identificatore univoco (event_id) che il ricevente registra dopo la prima elaborazione. Se arriva lo stesso event_id, risponde 200 ma non elabora di nuovo.
Validazione Timestamp: Prevenire Replay Attack
Un attaccante potrebbe intercettare una notifica webhook legittima e reinviarla più tardi. Per prevenirlo, il mittente include un timestamp nella richiesta (es. headerX-Timestamp: 1708000000). Il ricevente verifica che il timestamp non sia più vecchio di 5 minuti. Richieste scadute vengono rifiutate.
Esempi di Webhook nel Customer Support
Nuova Conversazione Chatbot
Il chatbot invia un webhook al CRM aziendale quando inizia una nuova conversazione, creando automaticamente un'attività nel sistema. Il team commerciale vede in tempo reale quante conversazioni attive ci sono senza dover controllare il pannello del chatbot.
Handoff Completato
Quando un operatore prende in carico una conversazione dal chatbot, un webhook notifica il sistema di ticketing. Il ticket viene aggiornato automaticamente con lo stato "in gestione" e l'operatore assegnato, senza nessun aggiornamento manuale.
Prenotazione Confermata
Quando il sistema di prenotazione conferma un appuntamento, invia un webhook al chatbot. Il bot può immediatamente rispondere all'utente con i dettagli della prenotazione confermata e inviare un reminder automatico via email o WhatsApp.
Aggiornamento Dati Cliente
Il CRM invia un webhook al chatbot quando i dati di un cliente vengono modificati (nuovo numero di telefono, cambio indirizzo). Il bot ha sempre informazioni aggiornate nella conversazione successiva, senza necessità di sincronizzazione periodica.
Domande Frequenti
Cos'è un webhook?
Un webhook è una notifica HTTP automatica inviata da un sistema a un altro quando accade un evento. A differenza delle API che il client chiama attivamente, il webhook inverte la direzione: è il server a notificare il client. Questo rende i sistemi reattivi agli eventi in tempo reale senza sprecare risorse in chiamate periodiche inutili.
Differenza webhook vs API?
Con le API (polling), il client chiede ripetutamente "ci sono novità?", anche quando non ci sono. Con il webhook, il server risponde solo quando c'è effettivamente qualcosa da comunicare. Il webhook è più efficiente, più rapido e più scalabile. Il trade-off è che richiede un endpoint HTTPS pubblico e raggiungibile da internet.
Come si protegge un endpoint webhook?
Le tre misure principali sono: 1) Firma HMAC per verificare autenticità del mittente, 2) Validazione timestamp per prevenire replay attack, 3) Idempotency check tramite event_id per evitare elaborazioni doppie. Sempre su HTTPS, mai su HTTP non cifrato. Opzionalmente, whitelist degli IP del mittente.
Termini Correlati
Implementa Webhook nella Tua Azienda
Scopri come V Support può aiutarti a sfruttare l'AI per il tuo customer service. Demo gratuita di 30 minuti.