Programmazione · concetti · web

Che cos’è un webhook?

Configuri un pagamento, e la tua applicazione reagisce nell’istante in cui il denaro viene incassato. Pushi un commit, e una build parte da sola. Dietro questa immediatezza c’è quasi sempre un webhook. Questa guida spiega, in modo semplice, che cos’è un webhook, in cosa differisce da una chiamata API classica, come riceverlo in sicurezza e dove già ne dipendi.

La definizione breve

Un webhook è una richiesta HTTP automatica che un servizio invia a un URL che controlli tu quando si verifica un evento. Anziché chiedere notizie a un servizio, è lui ad avvisare te non appena ce ne sono.

Da qui il soprannome di «API inversa». Con una API classica, sei il client: fai la richiesta, il server risponde. Con un webhook i ruoli si invertono — il fornitore diventa il client e il tuo endpoint è il server che lui chiama.

Webhook vs polling di una API

Prima dei webhook, il modo abituale di restare aggiornati era il polling: chiamare una API su un timer («ci sono novità?») di continuo. È semplice ma dispendioso — la maggior parte delle chiamate non restituisce nulla, e c’è sempre uno scarto tra l’evento e la verifica successiva.

• Polling — chiedi in loop. Molte richieste inutili, reazione ritardata, semplice da costruire.
• Webhook — il servizio ti avvisa una volta, immediatamente. Efficiente e quasi in tempo reale, ma devi far girare un endpoint per riceverlo.

Come funziona, passo dopo passo

1. Registri un URL (il tuo endpoint) presso il fornitore e scegli gli eventi che ti interessano.
2. Quando un tale evento si verifica, il fornitore invia un POST HTTP al tuo URL con un corpo (spesso JSON) che lo descrive.
3. Il tuo server legge il contenuto, restituisce in fretta uno stato 2xx per accusarlo, e fa il vero lavoro dopo.
4. Se il tuo endpoint è offline o restituisce un errore, la maggior parte dei fornitori ritenta con backoff — da qui i possibili doppioni.

Una consegna assomiglia a una qualsiasi richiesta HTTP:

POST /webhooks/payments  HTTP/1.1
Host: latuaapp.com
X-Signature: t=1718600000,v1=9f86d08...

{ "event": "payment.succeeded", "id": "pay_42", "amount": 1999 }

Esempi che conosci già

• Pagamenti — Stripe e PayPal inviano un webhook quando un pagamento va a buon fine, fallisce o viene rimborsato, così che la tua app aggiorni l’ordine senza polling.
• Hosting di codice — GitHub e GitLab attivano un webhook su push, pull request o issue: è così che vengono avviati build CI e bot.
• Messaggistica — Slack, Discord e le piattaforme di chat usano webhook in entrata per pubblicare messaggi e notificare la tua app.

Riceverlo in sicurezza

Un ricevitore robusto fa quattro cose:

• Servire in HTTPS e accettare i POST; rispondere in fretta con un 2xx, poi elaborare in modo asincrono.
• Verificare la firma — i fornitori firmano il corpo (un HMAC con un segreto condiviso). Rifiutare ciò che fallisce.
• Essere idempotente — lo stesso evento può arrivare più volte; usa l’id dell’evento affinché la riconsegna sia senza effetto.
• Restituire gli errori onestamente — se non puoi elaborare, restituisci un non-2xx affinché il fornitore ritenti invece di rinunciare.

I webhook hanno bisogno di un endpoint sempre online con un URL HTTPS pubblico — ecco perché un piccolo server o un’istanza cloud è la casa abituale di un ricevitore di webhook, anziché una macchina che va in standby.

Domande frequenti

Che cos’è un webhook, in parole semplici?

Un webhook è un messaggio automatico che un servizio invia a un URL che controlli tu nell’istante in cui qualcosa accade — per esempio «un pagamento è andato a buon fine» o «un commit è stato pushato». Invece di chiedere continuamente al servizio «ci sono novità?» (il polling della sua API), il servizio ti chiama con una richiesta HTTP POST appena l’evento si verifica. Si parla spesso di «API inversa»: con una API classica sei tu a fare la richiesta; con un webhook è il servizio a farla a te.

Qual è la differenza tra un webhook e una API?

Sono collegati ma vanno in senso inverso. Con una API (REST) classica, invii una richiesta al fornitore quando vuoi dei dati, e lui risponde. Con un webhook, il fornitore invia una richiesta al tuo server quando si verifica un evento: i dati ti vengono spinti quasi in tempo reale senza chiedere nulla. Un webhook passa per la stessa meccanica HTTP di una API — è il fornitore a fare la parte del client e il tuo endpoint quella del server.

Perché un webhook invece del polling?

Il polling consiste nel chiamare una API a intervalli regolari per controllare i cambiamenti, il che spreca richieste e aggiunge un ritardo tra l’evento e la tua reazione. I webhook ti spingono l’evento nell’istante in cui arriva: più efficienti e molto più vicini al tempo reale. In cambio, devi far girare un endpoint sempre online e gestire i ritentativi e le consegne in doppio.

Come ricevere un webhook in sicurezza?

Esponi un endpoint HTTPS che accetta i POST, restituisci in fretta uno stato 2xx per accusare ricezione, poi elabora il lavoro in modo asincrono. Verifica la firma che il fornitore invia (un HMAC del corpo con un segreto condiviso) per confermare l’autenticità, e rendi l’elaborazione idempotente perché uno stesso evento può essere consegnato più volte. Rifiuta tutto ciò che non supera la verifica della firma.

In sintesi

Un webhook è il modo del web di dire «non chiamarci, ti chiamiamo noi»: una richiesta HTTP automatica che un servizio invia al tuo endpoint non appena si verifica un evento. È più efficiente e molto più in tempo reale del polling di una API — al prezzo di un endpoint affidabile, che verifica le firme, per riceverlo. Una volta individuati, vedrai i webhook dietro quasi ogni «si è aggiornato da solo» del software moderno.