Un webhook è un meccanismo con cui un sistema invia automaticamente una richiesta HTTP a un URL configurato quando si verifica un determinato evento.
Un pagamento viene confermato, un ordine cambia stato, un modulo viene inviato o un repository riceve un nuovo push: invece di aspettare che l’applicazione interessata controlli continuamente se qualcosa è cambiato, il sistema sorgente può avvisarla nel momento in cui accade.
È questo il modello mentale da tenere a mente:
evento → richiesta HTTP → endpoint ricevente → verifica → risposta → elaborazione
La definizione sembra semplice. La parte interessante arriva quando un webhook deve funzionare davvero: la stessa consegna può arrivare più di una volta, gli eventi possono non rispettare l’ordine atteso, il destinatario può essere temporaneamente irraggiungibile e una richiesta apparentemente valida non deve essere considerata autentica soltanto perché raggiunge l’endpoint corretto.
Per questo webhook e API non sono semplicemente due alternative da mettere una contro l’altra. Spesso lavorano insieme: il webhook segnala che è successo qualcosa, mentre una successiva chiamata API consente di recuperare lo stato corrente o eseguire un’azione.
Vediamo come funziona questo modello, dove conviene utilizzarlo e quali accorgimenti fanno la differenza tra una demo funzionante e un’integrazione affidabile.
Cos’è un webhook e a cosa serve
Un webhook permette a un’applicazione di ricevere una comunicazione quando si verifica un evento per il quale è stata configurata.
Immagina un ecommerce collegato a un sistema esterno di gestione ordini. Il gestionale deve sapere quando un pagamento viene completato.
Un approccio potrebbe essere interrogare periodicamente il sistema di pagamento:
questo pagamento è stato completato?
Se la risposta è no, aspetta e riprova.
Poi riprova ancora.
Con un webhook il flusso viene capovolto: quando si verifica l’evento, è il sistema che lo ha generato a inviare una richiesta all’indirizzo configurato dal destinatario.
Nel caso precedente:
pagamento completato → evento generato → webhook inviato → backend dell’ecommerce riceve la notifica
Il webhook è quindi particolarmente utile per sistemi event-driven, nei quali un’applicazione deve reagire a qualcosa che accade altrove senza interrogare continuamente il provider.
Non è però un protocollo autonomo paragonabile a HTTP. È più corretto considerarlo un pattern di comunicazione applicativa, implementato normalmente attraverso richieste HTTP o HTTPS.
Evento, callback URL ed endpoint: i tre elementi da capire
Per capire un webhook bastano inizialmente tre componenti.
Il primo è l’evento.
Può essere, per esempio:
- un pagamento riuscito;
- un pagamento fallito;
- la creazione di un ordine;
- una nuova registrazione;
- l’invio di un form;
- la modifica di una risorsa;
- un push su un repository;
- la cancellazione di un abbonamento.
Il secondo elemento è l’URL configurato per ricevere la richiesta. Viene spesso chiamato webhook URL, callback URL o endpoint del webhook, anche se la terminologia precisa può cambiare da piattaforma a piattaforma.
Potrebbe avere una forma concettuale simile a:
/webhooks/payments
Il terzo elemento è l’handler, cioè la logica lato server che riceve e gestisce la richiesta.
Il suo compito non dovrebbe limitarsi a leggere il contenuto ricevuto. In un’integrazione robusta deve anche verificare che la consegna sia autentica, capire quale evento rappresenta, evitare elaborazioni duplicate e decidere che cosa fare dopo.
Come funziona un webhook, passo dopo passo
Supponiamo di avere un’applicazione che deve reagire a un pagamento completato.
Il flusso tipico può essere rappresentato così:
evento → provider → richiesta HTTP → endpoint → verifica → deduplicazione → conferma → elaborazione
Ogni provider definisce il proprio contratto: nomi degli eventi, struttura del payload, header, meccanismo di autenticazione, strategia di retry e codici di risposta attesi possono cambiare.
Per questo non basta sapere genericamente “come funzionano i webhook”. Devi sempre leggere anche la documentazione del servizio che li invia.
Dal trigger alla richiesta HTTP
Il processo inizia da un trigger.
Il sistema sorgente rileva una condizione per la quale esiste una sottoscrizione webhook. Genera quindi l’evento e prepara una richiesta destinata all’URL registrato.
Molti webhook utilizzano POST, perché devono inviare dati al destinatario, ma non conviene trasformare questa convenzione in una definizione universale: ciò che conta è il contratto stabilito dal provider.
La richiesta può contenere:
- header HTTP;
- identificativo della consegna o dell’evento;
- tipo di evento;
- timestamp;
- firma o altri dati di verifica;
- payload con i dati associati all’evento.
Il server destinatario riceve la richiesta e decide se accettarla.
Solo dopo dovrebbe iniziare la logica applicativa prevista.
Cosa contiene il payload
Il payload è il contenuto trasportato dal webhook.
Molte piattaforme utilizzano JSON perché rappresenta facilmente oggetti, array e strutture annidate, ma anche in questo caso il formato dipende dal servizio.
Un esempio puramente illustrativo potrebbe essere:
{
"id": "evt_7F82A",
"type": "payment.completed",
"data": {
"order_id": "ORD-1048",
"amount": 8990,
"currency": "EUR"
}
}
Da questo payload l’applicazione può ricavare almeno tre informazioni:
- quale consegna sta gestendo;
- quale evento si è verificato;
- a quale risorsa dell’applicazione si riferisce.
Il campo id è particolarmente importante quando può essere utilizzato per identificare una consegna già elaborata.
I nomi mostrati nell’esempio non costituiscono però uno standard. Un provider reale può adottare una struttura completamente diversa.
Cosa deve fare il sistema che riceve il webhook
Una prima implementazione potrebbe sembrare banale:
- ricevi il
POST; - leggi il JSON;
- aggiorna il database;
- restituisci
200 OK.
In produzione manca parecchio.
Un handler affidabile dovrebbe ragionare piuttosto così:
ricevi → verifica origine/integrità → valida evento → controlla duplicati → registra → conferma la ricezione → elabora
A seconda dell’architettura, l’elaborazione vera e propria può essere delegata a una coda asincrona.
È una distinzione importante. La richiesta webhook è un canale di consegna; non dovrebbe necessariamente restare aperta mentre l’applicazione genera fatture, invia email, aggiorna CRM, sincronizza inventario e svolge altre operazioni costose.
Webhook vs API: qual è davvero la differenza
La formula “API pull, webhook push” è utile per iniziare, ma diventa imprecisa se viene presa alla lettera.
Un’API definisce come un software può richiedere dati o operazioni a un altro sistema. Un webhook definisce invece un meccanismo con cui un sistema può notificare un evento a un endpoint configurato.
Il polling è soltanto una possibile modalità di utilizzo di un’API, non la definizione di API.
| Aspetto | API con richiesta diretta | Webhook | Polling | WebSocket |
|---|---|---|---|---|
| Chi avvia la comunicazione | il client | il sistema che genera l’evento | il client, periodicamente | entrambe le parti dopo la connessione |
| Quando avviene | quando il client ne ha bisogno | quando si verifica l’evento | a intervalli definiti | durante una connessione persistente |
| Modello tipico | request/response | event notification | richieste ripetute | comunicazione bidirezionale |
| Ideale per | leggere o modificare risorse | reagire a eventi | controlli semplici o fallback | flussi continui e interattivi |
| Problemi da gestire | errori, autenticazione, rate limit | retry, duplicati, firma, ordine | latenza e richieste inutili | connessioni, stato e scalabilità |
Richiesta client-initiated e comunicazione event-driven
Con una normale richiesta API è il client a decidere quando comunicare.
Per esempio:
GET /orders/123
significa concettualmente:
dimmi qual è lo stato dell’ordine 123.
Con un webhook può essere il sistema esterno a comunicare:
l’ordine 123 è appena stato spedito.
La differenza non riguarda quindi soltanto il formato dei dati. Cambia chi prende l’iniziativa e quale evento avvia la comunicazione.
Webhook vs polling
Nel polling un’applicazione effettua controlli periodici.
Supponiamo che un sistema interroghi ogni minuto lo stato di un pagamento.
Se il pagamento viene completato due secondi dopo l’ultimo controllo, l’applicazione lo scoprirà con la richiesta successiva. Se invece non succede nulla per molte ore, continuerà comunque a produrre richieste.
Un webhook permette di evitare questo schema quando il provider espone gli eventi necessari.
Questo può ridurre:
- richieste prive di nuovi dati;
- latenza dovuta all’intervallo di polling;
- consumo dei limiti dell’API;
- logica di scheduling non necessaria.
Non significa che il polling sia sempre sbagliato.
Può essere perfettamente ragionevole quando il servizio non offre webhook, quando gli aggiornamenti sono poco frequenti, quando una verifica periodica è sufficiente oppure come meccanismo di riconciliazione per controllare che lo stato locale sia rimasto coerente con quello remoto.
Perché webhook e API spesso si usano insieme
Questo è il modello che preferisco per capire la relazione:
webhook = segnale
API = accesso allo stato o alle operazioni
Immagina di ricevere una notifica che comunica:
invoice.paid
Il webhook può contenere già tutte le informazioni necessarie. In altri casi può essere più prudente utilizzare l’identificativo ricevuto e interrogare l’API del provider per recuperare lo stato corrente dell’oggetto.
Il secondo approccio diventa utile anche quando:
- gli eventi sono arrivati fuori ordine;
- manca qualche informazione;
- vuoi ricostruire lo stato dopo un’interruzione;
- devi riconciliare periodicamente il database locale.
Un sistema maturo non considera necessariamente webhook e API concorrenti. Li utilizza per compiti differenti.
Webhook vs WebSocket: quando cambia il tipo di comunicazione
I WebSocket risolvono un problema ancora diverso.
Dopo l’apertura della connessione permettono una comunicazione persistente e bidirezionale tra client e server.
Un webhook, invece, è normalmente una consegna puntuale legata a un evento.
Se devi aggiornare il tuo backend quando viene pagata una fattura, un webhook è naturale.
Se stai costruendo una chat, un dashboard con aggiornamenti continui o un’esperienza collaborativa nella quale entrambe le parti devono scambiarsi molti messaggi durante una sessione, una connessione persistente può avere più senso.
Non esiste quindi una gerarchia:
webhook > API > WebSocket
Esistono problemi diversi che richiedono modelli diversi.
Esempio pratico di webhook: dal pagamento all’aggiornamento dell’ordine
I pagamenti sono uno degli scenari più utili per capire il meccanismo.
Supponiamo che un ecommerce utilizzi Stripe per elaborare un pagamento.
Il cliente completa il checkout.
A questo punto sarebbe rischioso basare l’intera logica dell’ordine soltanto su ciò che accade nel browser del cliente. Una pagina potrebbe non caricarsi, l’utente potrebbe chiudere la scheda oppure il pagamento potrebbe attraversare stati che richiedono elaborazioni asincrone.
Il backend ha bisogno di una fonte server-to-server più affidabile per sapere che un determinato evento è avvenuto.
Il flusso completo dell’evento
Un possibile flusso è:
1. Il cliente avvia il pagamento
Il frontend comunica con l’infrastruttura prevista dal provider.
2. Il provider elabora il pagamento
Il processo può completarsi subito oppure richiedere ulteriori passaggi.
3. Si genera un evento rilevante
Per esempio, un evento che rappresenta la conferma del pagamento.
4. Il provider invia il webhook
La richiesta raggiunge l’endpoint configurato dall’ecommerce.
5. Il server verifica la consegna
Controlla firma e dati previsti dal contratto del provider.
6. L’applicazione verifica se l’evento è già stato processato
Se è un duplicato, non ripete l’azione commerciale.
7. Il server conferma rapidamente la ricezione
Il provider riceve una risposta di successo.
8. La logica applicativa continua
L’ordine può essere aggiornato, messo in coda per elaborazioni successive o sincronizzato con altri sistemi.
La documentazione sui webhook di Stripe raccomanda, tra le altre cose, di restituire rapidamente una risposta 2xx prima di eseguire logiche complesse.
Un esempio di payload JSON
Un payload semplificato potrebbe essere:
{
"id": "evt_payment_1048",
"type": "payment.completed",
"data": {
"order_id": "ORD-1048",
"payment_id": "PAY-7842",
"amount": 8990,
"currency": "EUR"
}
}
L’handler non dovrebbe leggere payment.completed e aggiornare immediatamente qualsiasi ordine indicato nel JSON.
Prima deve stabilire se quella consegna è autentica e se il contenuto è coerente con ciò che l’applicazione si aspetta.
Perché non conviene eseguire tutta la logica prima della risposta
Supponiamo che dopo il pagamento il sistema debba:
- aggiornare l’ordine;
- generare una fattura;
- sincronizzare il CRM;
- aggiornare il magazzino;
- inviare un’email;
- chiamare un gestionale esterno.
Se esegui tutto durante la stessa richiesta webhook, basta che un servizio rallenti per aumentare il rischio di timeout.
Una strategia più robusta è spesso:
ricezione → verifica → registrazione → conferma → coda → elaborazione
Il provider sa rapidamente che la consegna è arrivata. L’applicazione può svolgere il lavoro più pesante separatamente.
Cosa succede quando un webhook fallisce
La vera differenza tra una spiegazione teorica e un’integrazione affidabile emerge qui.
Una rete non è perfetta. I server possono essere occupati. Un deployment può rendere temporaneamente indisponibile un endpoint. Una consegna può essere ripetuta.
Devi quindi progettare il sistema partendo da una premessa:
una singola richiesta riuscita al primo tentativo non è l’unico scenario possibile.
Retry e backoff
Molti provider tentano nuovamente la consegna quando l’endpoint non risponde correttamente.
Il comportamento non è universale: numero dei tentativi, durata della finestra, intervalli e codici considerati fallimenti dipendono dal servizio.
Stripe, per esempio, documenta retry automatici in modalità live per un periodo che può arrivare fino a tre giorni, con intervalli progressivi.
Questo produce una conseguenza pratica: un errore temporaneo non deve trasformare automaticamente un evento in un dato perso.
Ma introduce il problema successivo.
Eventi duplicati e idempotenza
Se una consegna viene ritentata, la tua applicazione può ricevere più volte lo stesso evento.
Immagina un handler che esegua:
payment.completed → crea fattura
Se la stessa consegna arriva due volte e ogni esecuzione crea una nuova fattura, hai un problema.
L’operazione dovrebbe essere idempotente: ripetere lo stesso input non dovrebbe generare un secondo effetto commerciale indesiderato.
Una strategia comune consiste nel registrare l’identificativo dell’evento o della consegna già processata.
Il flusso diventa:
ricevi ID → cerca ID nel registro → se già presente, non ripetere → se nuovo, processa e registra
La documentazione Shopify sulla verifica delle consegne affronta esplicitamente questo caso e raccomanda operazioni idempotenti per impedire che una consegna duplicata produca un risultato diverso.
Eventi fuori ordine
Un altro errore comune consiste nel pensare:
se A è avvenuto prima di B, riceverò necessariamente A prima di B.
Non è sempre vero.
Stripe documenta esplicitamente che l’ordine di consegna degli eventi non è garantito.
Un sistema che dipende rigidamente da:
created → updated → paid
può quindi entrare in uno stato incoerente se riceve prima un evento successivo.
La soluzione non consiste nell’inventare un ordinamento dal timestamp. Devi progettare la logica in funzione del provider e, quando necessario, recuperare lo stato corrente della risorsa tramite API.
Eventi mancanti e riconciliazione tramite API
Anche con retry e code, un sistema critico dovrebbe prevedere una strategia di riconciliazione.
L’obiettivo è poter rispondere periodicamente a una domanda:
lo stato salvato localmente corrisponde ancora allo stato autorevole del provider?
Per un sistema di pagamenti potrebbe significare controllare le transazioni recenti.
Per un gestionale, confrontare ordini o inventario.
Per una piattaforma SaaS, ricostruire oggetti modificati durante un periodo di indisponibilità.
Ecco perché webhook e API si completano bene:
webhook per reagire rapidamente
API per verificare e ricostruire lo stato
Come rendere sicuro un webhook
Un webhook raggiunge un endpoint pubblico della tua applicazione.
Questo rende la sicurezza parte del design, non un’aggiunta da fare dopo.
La domanda centrale è:
come faccio a sapere che questa richiesta proviene davvero dal servizio che dichiara di averla inviata?
HTTPS è necessario, ma non autentica da solo il mittente
HTTPS protegge i dati durante il trasporto attraverso TLS.
È indispensabile per evitare che informazioni e credenziali viaggino in chiaro su una connessione non protetta.
Ma risolve un problema diverso dall’autenticità applicativa.
Un endpoint HTTPS pubblico può comunque ricevere richieste costruite da soggetti che conoscono il suo URL.
Quindi:
HTTPS protegge il canale
non equivale a:
qualsiasi richiesta arrivata su HTTPS è autentica
Firma del payload e secret
Molti provider adottano un secret condiviso e una firma crittografica.
Il principio è questo:
- il provider genera una firma utilizzando il contenuto della richiesta e un secret;
- invia payload e firma;
- il destinatario calcola o verifica la firma usando il secret configurato;
- se i valori non corrispondono, la richiesta viene rifiutata.
GitHub, per esempio, documenta la verifica delle consegne mediante HMAC SHA-256 e l’header X-Hub-Signature-256. La guida ufficiale di GitHub alla validazione dei webhook mostra il meccanismo e raccomanda di configurare un secret.
Non riutilizzare questo dettaglio alla cieca con altri provider: nomi degli header, algoritmi e procedura di verifica appartengono al relativo contratto.
Timestamp e protezione dai replay
Una firma valida dimostra che il messaggio è compatibile con il secret utilizzato, ma può essere necessario considerare anche i replay attack.
Un attaccante che riuscisse a intercettare una richiesta valida potrebbe tentare di reinviarla successivamente.
Alcuni provider includono quindi un timestamp nella firma o nel meccanismo di verifica e consentono di accettare soltanto consegne sufficientemente recenti.
Stripe adotta questo approccio nella propria procedura di firma.
La regola pratica resta:
implementa esattamente la strategia di verifica documentata dal provider, compresi eventuali controlli temporali.
Perché il raw body può essere importante
Questo dettaglio causa molti bug.
La firma può essere calcolata sui byte esatti del payload inviato.
Se il framework:
- interpreta il JSON;
- modifica spazi;
- ricodifica caratteri;
- ricostruisce l’oggetto;
- cambia il body prima della verifica;
il contenuto risultante potrebbe non coincidere più con quello firmato.
Stripe e Shopify richiedono esplicitamente il raw request body nei rispettivi processi di verifica.
Quindi l’ordine corretto può essere:
ricevi raw body → verifica firma → interpreta il payload → elabora
e non:
parse JSON → ricostruisci body → prova a verificare
È un dettaglio piccolo solo finché non passi dalla documentazione al codice reale.
Come testare e fare debug di un webhook
Quando un webhook non funziona, evitare di cambiare contemporaneamente endpoint, payload, secret e codice.
Conviene seguire il percorso reale della richiesta.
Controllare URL, header, payload e status HTTP
Inizia da quattro domande:
1. La richiesta è partita?
Controlla il registro delle consegne del provider, se disponibile.
2. Ha raggiunto l’endpoint corretto?
Verifica URL, DNS, HTTPS, firewall, reverse proxy e routing applicativo.
3. Che cosa ha ricevuto il server?
Controlla metodo, header, Content-Type, dimensione del body e identificativo della consegna.
4. Che cosa ha risposto l’applicazione?
Un 2xx, un 4xx, un 5xx e un timeout descrivono problemi completamente diversi.
Non limitarti quindi a “il webhook non arriva”.
Devi capire:
provider → rete → web server → route → verifica → handler → risposta
e individuare in quale punto si interrompe il flusso.
Log e identificativi degli eventi
Un buon log dovrebbe permettere di correlare una consegna senza memorizzare indiscriminatamente dati sensibili.
Sono spesso utili:
- identificativo dell’evento;
- tipo di evento;
- ora di ricezione;
- esito della verifica;
- status restituito;
- tempo di elaborazione;
- eventuale job asincrono creato;
- errore normalizzato.
Evita invece di scrivere nei log secret, token o payload completi quando contengono dati personali o informazioni riservate non necessarie al debugging.
Test, sandbox e produzione
Se il provider offre ambienti separati, tieni distinti:
- endpoint di test;
- endpoint live;
- secret;
- configurazioni;
- dati.
Poi prova deliberatamente anche gli scenari che normalmente vorresti evitare:
- firma errata;
- evento sconosciuto;
- payload incompleto;
- evento duplicato;
- risposta
500; - timeout;
- consegna fuori ordine.
Un handler che funziona soltanto con una richiesta perfetta non è ancora stato testato nei punti che contano.
Quando usare un webhook e quando scegliere un’alternativa
Il fatto che una piattaforma supporti webhook non significa che ogni integrazione debba usarli.
La scelta dipende dal tipo di comunicazione che ti serve.
Quando il webhook è la scelta naturale
Lo sceglierei quando:
- devi reagire a eventi generati da un sistema esterno;
- non sai in anticipo quando si verificheranno;
- vuoi evitare polling continuo;
- il provider espone eventi sufficientemente granulari;
- una comunicazione server-to-server è adatta al workflow;
- puoi gestire retry, autenticità e idempotenza.
Pagamenti, ordini, lead, abbonamenti e automazioni sono esempi classici.
Quando il polling può essere sufficiente
Il polling resta sensato quando:
- non esiste un webhook adatto;
- l’aggiornamento non deve essere immediato;
- controlli pochi oggetti a intervalli ampi;
- la semplicità operativa conta più della latenza;
- stai implementando una riconciliazione periodica.
Un processo che controlla una volta al giorno dieci record non ha necessariamente bisogno di un’architettura event-driven completa.
Quando serve una connessione persistente
Se il problema richiede scambio frequente e bidirezionale durante una sessione, il webhook può essere il modello sbagliato.
Una chat, un editor collaborativo o una dashboard con aggiornamenti continui possono richiedere WebSocket, Server-Sent Events o altre architetture progettate per comunicazioni persistenti o streaming.
La decisione può essere riassunta così:
| Esigenza | Modello da valutare per primo |
|---|---|
| Richiedere dati o eseguire un’operazione | API |
| Essere avvisati quando accade un evento | Webhook |
| Controllare periodicamente uno stato | Polling |
| Scambiare messaggi continuamente in entrambe le direzioni | WebSocket |
| Recuperare lo stato dopo eventi persi | API / riconciliazione |
Esempi e casi d’uso dei webhook
Una volta capito il modello, i casi d’uso diventano molto più facili da riconoscere.
Pagamenti ed ecommerce
Nei pagamenti i webhook possono segnalare:
- esito di una transazione;
- rimborso;
- contestazione;
- modifica di un abbonamento;
- evento legato alla fatturazione.
In un ecommerce possono invece partecipare alla sincronizzazione di ordini, inventario, spedizioni e altri processi.
Se lavori su WordPress, la distinzione con le REST API di WooCommerce è particolarmente utile: l’API permette a un’applicazione autorizzata di interrogare o modificare risorse dello shop, mentre un webhook può segnalare che un evento è avvenuto.
Form, CRM e marketing automation
Un form può generare un evento dopo l’invio.
Il payload può essere inviato a:
- CRM;
- piattaforma di automazione;
- sistema di lead management;
- applicazione interna;
- workflow personalizzato.
Anche qui il webhook non rappresenta l’intero processo. È il passaggio che innesca il workflow.
Il ricevente deve poi decidere come validare, trasformare e utilizzare i dati.
Un altro caso molto chiaro è la WhatsApp Business API: la Cloud API viene usata per eseguire operazioni sulla piattaforma, mentre i webhook permettono al backend di ricevere messaggi, stati ed eventi e reagire nel processo aziendale.
GitHub e workflow di sviluppo
GitHub utilizza webhook per notificare numerosi eventi legati ai repository.
Un’applicazione può reagire, per esempio, a un push, a una pull request o ad altri eventi supportati.
È il modello ideale per comprendere perché un webhook non è soltanto una funzionalità ecommerce: qualsiasi sistema che produce eventi e deve comunicarli a servizi esterni può adottare questo pattern.
Make, n8n e Zapier
Le piattaforme di automazione rendono i webhook accessibili anche senza costruire da zero il sistema ricevente.
In molti workflow puoi ottenere un endpoint, configurarlo nell’applicazione sorgente e usare i dati ricevuti come trigger per i passaggi successivi.
Questo è molto comodo, ma non elimina i concetti spiegati fin qui.
Anche in un ambiente low-code o no-code restano da capire:
- quali dati arrivano;
- chi può chiamare l’endpoint;
- cosa succede in caso di errore;
- come vengono gestiti i duplicati;
- quali informazioni vengono memorizzate;
- quali limiti e politiche applica la piattaforma.
L’interfaccia può diventare più semplice. Il modello di affidabilità sottostante non scompare.
Conclusione
Il webhook è uno dei meccanismi più utili quando due sistemi devono reagire a eventi senza interrogarsi continuamente.
La definizione essenziale è semplice:
succede qualcosa → il sistema sorgente invia una richiesta all’endpoint configurato
Ma fermarsi qui significa capire solo il caso ideale.
Un’implementazione realmente affidabile deve considerare anche verifica della firma, retry, duplicati, idempotenza, ordine degli eventi, timeout, elaborazione asincrona e riconciliazione dello stato.
Se devi soltanto recuperare dati o impartire un comando, parti dall’API. Se devi essere avvisato quando qualcosa accade, valuta un webhook. Nei sistemi più robusti, molto spesso, userai entrambi.
È proprio questa complementarità a rendere i webhook così utili: non sostituiscono l’interfaccia applicativa, ma permettono ai sistemi di sapere quando vale la pena reagire.