Cos'è un webhook e come funziona
Cos'è un webhook spiegato semplice: come funziona, differenza tra webhook e API tradizionali (polling vs push), esempi d'uso reali e come riceverne uno nel tuo progetto.
I webhook sono ovunque nel software moderno, eppure molti sviluppatori alle prime armi faticano a capirli. Il concetto, però, è semplice e geniale. In questo articolo ti spiego cos'è un webhook, come funziona e in cosa si distingue da una normale API, con esempi concreti.
Cos'è un webhook in parole semplici
Un webhook è un meccanismo con cui un'applicazione notifica automaticamente un'altra applicazione quando accade un evento, inviandole i dati in tempo reale. In pratica, è un modo per dire a un sistema: "quando succede questa cosa, avvisami subito a questo indirizzo".
L'analogia più efficace è quella del campanello di casa. Invece di affacciarti continuamente alla finestra per controllare se è arrivato qualcuno (faticoso e inefficiente), metti un campanello: quando arriva qualcuno, suona e tu lo sai all'istante. Il webhook è quel campanello.
Webhook vs API: polling contro push
Per capire i webhook, è utile confrontarli con il modo tradizionale di ottenere aggiornamenti tramite API:
- Polling (API tradizionale): la tua app chiede ripetutamente "è successo qualcosa? è successo qualcosa?" a intervalli regolari. Spreca risorse e introduce ritardo.
- Webhook (push): non chiedi nulla. È l'altro sistema che ti contatta quando l'evento accade, inviandoti i dati.
| Aspetto | Polling (API) | Webhook |
|---|---|---|
| Chi inizia | Tu chiedi | L'altro sistema ti avvisa |
| Tempistica | A intervalli | In tempo reale |
| Efficienza | Spreca richieste | Solo quando serve |
In sintesi: con l'API vai tu a chiedere, con il webhook ti vengono a dire. Per gli eventi che accadono in modo imprevedibile, il webhook è molto più efficiente.
Come funziona un webhook
Il flusso tipico:
- Ti registri presso un servizio fornendo un URL del tuo sito (l'endpoint webhook).
- Quando accade un evento (es. un pagamento completato), il servizio invia una richiesta HTTP a quel tuo URL.
- La richiesta contiene i dati dell'evento, di solito in formato JSON.
- Il tuo sistema riceve i dati e reagisce (es. attiva l'abbonamento dell'utente).
Tutto questo avviene in tempo reale, senza che tu debba controllare nulla attivamente.
Esempi d'uso reali
I webhook sono dappertutto. Qualche esempio concreto:
- Pagamenti: quando un pagamento va a buon fine, Stripe avvisa il tuo sito via webhook, così puoi sbloccare il prodotto o il servizio.
- Notifiche: un repository Git può avvisare un sistema di build ogni volta che fai un commit.
- Automazioni: strumenti come n8n o Zapier usano i webhook per scatenare flussi di automazione quando succede qualcosa.
- Messaggistica: un bot può ricevere i nuovi messaggi via webhook.
Come gestire un webhook in sicurezza
Ricevere un webhook significa esporre un endpoint pubblico, quindi servono alcune accortezze:
- Verifica l'autenticità: controlla che la richiesta arrivi davvero dal servizio atteso (di solito tramite una firma).
- Rispondi velocemente: conferma la ricezione subito, ed elabora i dati pesanti in seguito.
- Gestisci i duplicati: a volte lo stesso evento può arrivare più volte; il tuo sistema deve esserne consapevole.
In sintesi
Un webhook è un meccanismo con cui un'applicazione notifica un'altra in tempo reale quando accade un evento, inviandole i dati direttamente. A differenza del polling tradizionale (dove sei tu a chiedere aggiornamenti), con il webhook è l'altro sistema a contattarti, in modo molto più efficiente. È usatissimo per pagamenti, automazioni e notifiche.
Per il contesto più ampio, vedi cos'è un'API e, per usarli nelle automazioni, come automatizzare con n8n.