Webhook: cosa sono, come funzionano e quando usarli

Se hai mai sentito parlare di webhook ma non hai capito bene cosa siano, sei nel posto giusto. Quando si commissiona un progetto software che deve dialogare con sistemi esterni (gestionali, piattaforme di pagamento, CRM, e-commerce), prima o poi spunta questa parola. E quasi sempre arriva senza spiegazioni chiare.

In questa guida ti spiego in modo semplice cosa sono i webhook, come funzionano davvero, in cosa si differenziano dalle classiche API e quando conviene usarli nel tuo progetto. Niente gergo inutile: solo quello che ti serve per parlare con la tua software house senza sentirti spaesato.

Webhook: cosa sono in parole semplici

Un webhook è un meccanismo che permette a un'applicazione di inviare automaticamente dati a un'altra applicazione nel momento esatto in cui succede qualcosa. Si tratta, in pratica, di una notifica in tempo reale tra due sistemi.

L'analogia più chiara è quella del campanello di casa. Quando arriva un ospite, suona il campanello e tu vai ad aprire. Non devi controllare alla porta ogni cinque minuti per vedere se è arrivato qualcuno: è il campanello a chiamarti quando serve.

I webhook funzionano allo stesso modo: invece di interrogare continuamente un sistema esterno per chiedere "è successo qualcosa di nuovo?", aspetti che sia quel sistema a "suonare il campanello" quando un evento accade.

Un esempio concreto

Immagina di gestire un e-commerce. Vuoi che ogni volta che un cliente completa un pagamento su Stripe, il tuo gestionale interno aggiorni automaticamente lo stato dell'ordine, mandi una notifica al magazzino e generi la fattura.

Senza webhook, il tuo gestionale dovrebbe chiedere a Stripe ogni pochi secondi: "ci sono nuovi pagamenti?". Uno spreco di risorse enorme. Con un webhook, è Stripe stesso a contattare il tuo gestionale nel momento esatto in cui il pagamento va a buon fine, inviando tutte le informazioni utili in un solo colpo.

Come funzionano i webhook: il flusso passo per passo

Il funzionamento di un webhook si basa su tre attori: il sistema che genera l'evento (chiamato provider), l'URL di destinazione (l'endpoint) e il sistema che riceve la notifica (consumer). Ecco cosa succede nel dettaglio.

1. Registrazione dell'endpoint

Sul sistema provider (per esempio Stripe, GitHub, Mailchimp), tu o il tuo sviluppatore configurate un URL di destinazione. Quell'URL è un indirizzo che punta a una specifica parte della tua applicazione, pronta a ricevere dati.

2. L'evento accade

Sul provider succede qualcosa di rilevante: un pagamento, un nuovo iscritto, un commit nel codice, un'email aperta. Il provider rileva l'evento e prepara un pacchetto di dati che lo descrive.

3. Invio della richiesta HTTP

Il provider invia una richiesta HTTP (di solito un POST) all'URL che hai configurato, con un payload in formato JSON che contiene tutte le informazioni dell'evento: tipo, timestamp, dati specifici.

4. La tua app reagisce

La tua applicazione riceve il payload, lo legge ed esegue le azioni previste: aggiornare il database, mandare una notifica, lanciare un altro processo. Tutto in pochi millisecondi, senza che nessuno debba premere un bottone.

Webhook vs API: qual è la vera differenza

È la domanda più comune e la fonte di più confusione. Sia webhook che API servono a far comunicare due sistemi, ma il loro funzionamento è opposto.

Con una API tradizionale, sei tu a fare la prima mossa. La tua app interroga il sistema esterno con una richiesta e aspetta una risposta. Tecnicamente si chiama pull: tu vai a prendere le informazioni.

Con un webhook, è il sistema esterno a fare la prima mossa. Quando succede l'evento, è lui a contattarti e a "spingerti" i dati. Tecnicamente si chiama push: ti arrivano da soli.

Un modo semplice per ricordarlo: l'API è come una telefonata in cui chiami tu, il webhook è come un SMS che ricevi quando l'altro decide di mandartelo. Spesso, comunque, le due cose convivono nello stesso progetto: alcune comunicazioni avvengono via API, altre via webhook.

Quando conviene usare i webhook

I webhook non sono sempre la scelta giusta. Funzionano bene in scenari specifici, dove la loro logica "event-driven" porta vantaggi concreti.

Eventi reali in tempo reale

Se hai bisogno che il tuo sistema reagisca immediatamente a qualcosa che accade altrove (un pagamento, una spedizione, un messaggio ricevuto), il webhook è la soluzione naturale. Aspettare di interrogare l'API ogni minuto sarebbe inefficiente.

Risparmio di risorse

Fare richieste API continue costa: in banda, in CPU, a volte anche in denaro (molte API hanno limiti di chiamate). Con i webhook ricevi solo ciò che ti interessa, quando ti interessa. Zero rumore.

Integrazioni automatizzate

Qualsiasi flusso di lavoro tra strumenti diversi — Stripe che parla con il gestionale, GitHub che notifica Slack, Mailchimp che aggiorna il CRM — si appoggia tipicamente su webhook. Sono la spina dorsale dell'automazione moderna tra sistemi.

Se stai valutando un'integrazione tra più piattaforme per il tuo progetto, possiamo aiutarti a scegliere l'approccio giusto: contattaci dalla sidebar per una consulenza gratuita.

Errori comuni da evitare con i webhook

I webhook sembrano semplici sulla carta, ma in produzione possono dare grattacapi se non vengono gestiti bene. Ecco gli errori più diffusi che vediamo fare anche a team esperti.

Non validare la fonte della richiesta

Il tuo endpoint webhook è pubblico: qualsiasi malintenzionato può inviarci dati finti. Senza una firma digitale (di solito un header HMAC), il sistema rischia di processare richieste fasulle. Tutti i provider seri (Stripe, GitHub, PayPal) forniscono un meccanismo di firma: va sempre verificato.

Ignorare i tentativi di consegna falliti

Se il tuo server è down nel momento esatto in cui il webhook arriva, la notifica può andare persa. I provider migliori implementano un meccanismo di retry, ma la tua app deve rispondere correttamente (codice HTTP 200) per dire "ricevuto". Altrimenti il provider riproverà più volte e poi smetterà.

Non rendere idempotente la logica

Capita che lo stesso webhook arrivi due volte (per un retry, per un bug del provider, o per ridondanza). Se la tua logica non è idempotente, rischi di duplicare ordini, inviare email due volte, addebitare pagamenti doppi. Ogni webhook ha di solito un ID univoco: salvalo e ignora le richieste duplicate.

Eseguire troppa logica nell'endpoint

Un webhook deve rispondere velocemente: idealmente sotto i 5 secondi. Se nel tuo endpoint metti calcoli pesanti, invii email sincrone o lanci PDF, il provider potrebbe considerarlo fallito. Soluzione: nell'endpoint salva subito il dato in una coda, poi fai partire un processo asincrono che elabora con calma.

Non monitorare i webhook

I webhook vivono in background, silenziosi. Se uno fallisce, te ne accorgi solo quando un cliente ti chiama. Vanno monitorati attivamente: log strutturati, alert automatici, dashboard di stato. Senza monitoraggio, prima o poi si rompono e non lo sai.

Casi d'uso reali: dove trovi i webhook tutti i giorni

Probabilmente li stai già usando senza saperlo. Ecco i contesti più comuni in cui i webhook sono lo standard:

• Pagamenti: Stripe, PayPal, Square notificano via webhook ogni transazione (riuscita, fallita, rimborsata).
• E-commerce: Shopify, WooCommerce inviano webhook quando viene creato un ordine, aggiornato uno stock o registrato un cliente.
• CRM e marketing: HubSpot, Mailchimp, ActiveCampaign usano webhook per sincronizzare contatti tra strumenti.
• Sviluppo: GitHub, GitLab, Bitbucket notificano commit, pull request e deploy ai sistemi CI/CD.
• Messaging: Slack, Discord, Microsoft Teams ricevono notifiche da app esterne via webhook in entrata.
• SMS e telefonia: Twilio invia webhook quando un SMS viene ricevuto o quando una chiamata cambia stato.

Checklist pratica: il tuo progetto è pronto per i webhook?

Prima di farti proporre un'integrazione basata su webhook dalla tua software house, verifica che siano state messe a punto queste cose:

1. Endpoint dedicato: c'è un URL specifico per ogni provider, non un unico endpoint che riceve tutto in modo disordinato.
2. Verifica della firma: ogni richiesta in entrata viene validata con la chiave segreta del provider.
3. Idempotenza: la logica gestisce correttamente eventuali duplicati grazie a un ID univoco.
4. Risposta rapida: l'endpoint risponde sotto i 5 secondi, delegando l'elaborazione pesante a una coda asincrona.
5. Logging completo: tutte le richieste in entrata vengono salvate con timestamp, payload e risultato.
6. Alert sui fallimenti: se un webhook fallisce o non arriva per un certo tempo, qualcuno viene avvisato.
7. Documentazione interna: ogni webhook attivo è documentato (a cosa serve, dove punta, cosa scatena).

Se uno solo di questi punti manca, è il segnale che vale la pena fermarsi e chiedere chiarimenti prima di andare in produzione.

Conclusione

I webhook sono uno strumento potente per costruire applicazioni reattive, automatiche e ben integrate con il resto del mondo digitale. Capirli, anche solo a livello concettuale, ti permette di parlare con il tuo team di sviluppo in modo più consapevole e di pretendere implementazioni solide.

La buona notizia è che, una volta impostati bene, lavorano in silenzio per anni. La cattiva è che impostarli male crea problemi sottili che emergono solo nei momenti peggiori — di solito quando un cliente importante perde un ordine.

Hai bisogno di supporto per integrare webhook nel tuo progetto software o stai valutando un'architettura event-driven? Scrivici: trovi il form di contatto qui a destra. Saremo felici di darti un parere chiaro e senza fuffa.