Garanzie di consegna dei webhook spiegate

Le garanzie di consegna dei webhook descrivono con quale frequenza e in quale ordine un provider invia gli eventi al Suo endpoint. Nella maggior parte dei casi promettono una consegna almeno una volta: l’endpoint riceve quasi tutto, a volte due volte, a volte in ritardo o fuori ordine. Le integrazioni affidabili mettono le protezioni dal lato ricevente.

Questa guida spiega ogni garanzia in termini semplici, mostra che cosa promettono davvero la documentazione dei provider reali e si chiude con una checklist per qualsiasi integrazione di webhook, inclusi gli eventi di pagamento crypto.

TL;DR

• “Almeno una volta” è il limite realistico. I provider ritentano finché non ricevono una risposta 2xx, quindi i duplicati sono normali e vanno gestiti.
• L’ordine non è garantito. Un evento precedente andato in timeout può arrivare dopo uno successivo, quindi lo ordini in base al proprio campo di timestamp o di sequenza.
• Prima conferma, poi elabora. Verifichi la firma, salvi l’evento in modo durevole, restituisca 2xx, poi svolga il lavoro pesante in modo asincrono.
• Elimini i duplicati sull’ID dell’evento. Lo registri con un indice univoco prima di qualsiasi effetto collaterale, come l’accredito di un saldo.
• Consideri i webhook come notifiche, non come un registro contabile. Riconcili i record critici con l’API secondo una pianificazione, per intercettare ciò che i tentativi non hanno recuperato.
• Chaingateway non ritenta automaticamente le notifiche fallite. Le elenca e le reinvia su richiesta.

Che cosa significano le tre garanzie di consegna?

Le semantiche di consegna provengono dai sistemi distribuiti e si applicano con precisione ai webhook.

Garanzia	Che cosa fa il mittente	Che cosa può andare storto	Che cosa costruisce lei
Al massimo una volta	Invia l’evento una volta e non ritenta mai	L’evento va perso se il Suo endpoint è giù	Riconciliazione con l’API
Almeno una volta	Ritenta finché non riceve conferma o finché i tentativi si esauriscono	Duplicati, arrivi in ritardo, riordinamenti	Gestore idempotente, deduplicazione
Esattamente una volta	Consegnerebbe una sola volta, senza perdite né duplicati	Non raggiungibile attraverso un confine di rete inaffidabile	Almeno una volta più deduplicazione

Con al massimo una volta, un tentativo fallito significa un evento perso. È semplice per il mittente e pericoloso per qualsiasi cosa che coinvolga denaro.

Con almeno una volta, il mittente continua a provare finché non vede una risposta di successo o finché non esaurisce il budget di tentativi. La perdita diventa rara, ma c’è un inganno. Supponga che il Suo gestore accrediti un conto e poi vada in crash prima di restituire 200. Il mittente non ha visto la conferma, quindi invia di nuovo l’evento. Dal lato del mittente è un comportamento corretto. Dal Suo lato, è un doppio accredito, a meno che non lo impedisca.

Esattamente una volta è ciò che tutti vogliono e che nessuno può promettere su HTTP. Il mittente non può sapere se il Suo server ha elaborato la richiesta quando la connessione cade. Il sostituto pratico è la consegna almeno una volta combinata con un ricevitore che ignora le ripetizioni. Questa combinazione dà effetti esattamente una volta, che è ciò che conta davvero.

Che cosa promettono davvero i provider?

Legga la sezione sulla consegna nella documentazione di qualsiasi provider serio di webhook e troverà lo stesso schema.

Adobe I/O Events afferma che ogni evento viene consegnato almeno una volta per registrazione, che possono essere inviati duplicati e che l’ordine degli eventi non è garantito. Column, un’API bancaria statunitense, dichiara che non si garantisce che gli eventi webhook arrivino nell’ordine di creazione. Un evento precedente andato in timeout può arrivare dopo uno successivo, perché ogni tentativo viene riprogrammato in modo indipendente.

Quest’ultimo dettaglio spiega la maggior parte dei bug di ordine. L’evento A fallisce una volta e viene riprogrammato per un nuovo tentativo tra un minuto. L’evento B, creato dopo, riesce subito. Il Suo sistema vede B, poi A. Dal lato del provider non c’è nulla di rotto. La garanzia semplicemente non ha mai coperto l’ordine.

Ordine: usi l’orologio dell’evento, non quello della consegna

Le linee guida di Wise sui webhook consigliano di ricostruire la cronologia dai timestamp dell’evento o, dove disponibili, dagli ID di sequenza crescenti in modo monotono, invece che dal momento in cui la notifica è stata inviata. La loro documentazione osserva che l’ora di invio può differire da quella in cui l’evento si è verificato, soprattutto durante i tentativi.

In pratica:

1. Salvi il timestamp di business o il numero di sequenza dell’evento insieme al payload.
2. Quando arriva un evento, lo confronti con lo stato più recente che possiede per quell’oggetto.
3. Se l’evento in arrivo è più vecchio di quanto già applicato, lo registri ma non lasci che sovrascriva lo stato più recente.

Per uno stato di pagamento che passa da in sospeso a confermato, questo impedisce a un evento “pending” in ritardo di far tornare indietro un pagamento confermato.

Come funzionano i tentativi dei webhook, e quando si fermano?

Le politiche di tentativo variano, ma la forma è coerente: backoff esponenziale, un tetto massimo e un arresto definitivo. Chaingateway fa eccezione, perché non ritenta automaticamente.

Provider	Comportamento dei tentativi (dalla documentazione)
Column	Fino a 25 tentativi entro tre giorni, backoff esponenziale, primo tentativo un minuto dopo la consegna fallita
Probo	Fino a 12 tentativi, backoff esponenziale con jitter completo da una base di 30 secondi, con tetto a quattro ore
Stripe	Backoff esponenziale in modalità live per fino a tre giorni
Chaingateway	Nessun tentativo automatico. Le notifiche fallite sono elencate su GET /api/v2/{chain}/webhooks/notifications/failed e reinviate con POST /api/v2/{chain}/webhooks/notifications/{id}/retry

Fonti: documentazione di Column, Probo e Stripe, consultate il 5 novembre 2026, e la specifica OpenAPI di Chaingateway.

La documentazione di Probo aggiunge dettagli utili. Ritenta in caso di errori di rete, timeout e risposte 408, 425, 429 o 5xx, e rispetta un header Retry-After fino al suo tetto. Esaurite le richieste, la consegna viene segnata come fallita e non viene rimessa in coda.

Ne derivano due lezioni. Primo, i codici di errore del Suo endpoint sono segnali: un 5xx dice al mittente di riprovare, quindi lo restituisca solo quando vuole davvero un nuovo tentativo. Secondo, la finestra dei tentativi è finita. Se il Suo servizio è giù più a lungo della finestra, quegli eventi escono dalla coda dei tentativi e Lei ha bisogno di un altro modo per recuperarli.

Perché conviene confermare in fretta ed elaborare dopo?

Una consegna risulta riuscita quando restituisce uno stato 2xx. Column considera un evento consegnato quando riceve un 2xx entro 10 secondi e raccomanda di restituirlo subito dopo la ricezione, prima di un’elaborazione sostanziale. La documentazione di NestJS considera 2xx come successo e tutto il resto, inclusi reindirizzamenti, timeout e connessioni rifiutate, come fallimento.

Quindi il compito del gestore è ristretto:

1. Legga il corpo grezzo.
2. Verifichi la firma.
3. Controlli il tipo e l’ID dell’evento.
4. Scriva l’evento in uno storage durevole (una riga di database o un messaggio in coda).
5. Restituisca 200, 202 o 204.

Tutto il resto, come aggiornare i saldi, inviare email o chiamare altri servizi, gira in un worker che legge da quello storage. Se svolge il lavoro lento in linea, una query lenta diventa un timeout, il timeout diventa un tentativo e il tentativo diventa un duplicato. L’approccio ingest, coda e fan-out è trattato nel nostro articolo su webhook e WebSocket.

Come rendo innocui i duplicati?

Poiché la consegna almeno una volta comporta ripetizioni, il gestore deve essere idempotente. Il metodo standard è semplice.

Le linee guida di Probo sono di verificare la firma, confermare l’organizzazione e il tipo di evento attesi, poi registrare in modo atomico l’ID dell’evento con un indice univoco prima di qualsiasi effetto collaterale. Una richiesta successiva che porta un ID già registrato viene ignorata. Stripe dà lo stesso consiglio: registrare gli ID degli eventi elaborati e saltare qualsiasi evento già gestito. Molti provider lo rendono facile includendo un ID univoco in ogni payload. Adobe, ad esempio, inserisce un UUID nel payload e lo ripete in un header x-adobe-event-id.

Uno schema minimo:

1. Inserisca l’ID dell’evento in una tabella con un vincolo di unicità.
2. Se l’inserimento fallisce perché l’ID esiste già, restituisca 200 e si fermi.
3. Se riesce, metta in coda il lavoro.

L’ordine conta. Prima registri, poi agisca. Se agisce per primo e va in crash prima di registrare, il tentativo ripeterà l’azione. Se registra per primo e va in crash prima di agire, il worker dovrebbe riprendere i record non completati al riavvio, così l’evento non viene scartato in silenzio.

Per i movimenti di denaro, aggiunga un secondo livello: renda idempotente anche l’operazione di business. Associ l’accredito di un deposito all’hash della transazione e all’indice del log, oppure all’ID del pagamento, così anche un bug nella tabella degli eventi non può accreditare due volte lo stesso pagamento.

Come verifico ogni richiesta?

Un endpoint webhook è un URL pubblico che attiva azioni nel Suo sistema. Chiunque può inviarvi un POST, a meno che Lei non verifichi chi ha inviato la richiesta.

Stripe richiede la verifica usando il corpo grezzo della richiesta, l’header della firma e il segreto del Suo endpoint. Il consiglio di Probo è usare il corpo non modificato e verificare la firma prima di analizzare il JSON, poi applicare un controllo di freschezza del timestamp. Analizzare e ri-serializzare il corpo prima della verifica è una causa classica di firme che non corrispondono mai.

Una procedura di verifica solida per i provider che firmano il corpo:

• Calcoli l’HMAC sui byte esatti ricevuti, usando il Suo segreto.
• Confronti il valore con quello dell’header tramite un confronto a tempo costante.
• Respinga le richieste il cui timestamp è fuori da una breve finestra di tolleranza, per limitare la riproduzione di catture.
• Solo allora analizzi il JSON e controlli il tipo di evento.

Chaingateway funziona diversamente. Calcola un HMAC-SHA256 in Base64 sul txid del payload e lo invia nell’header X-Signature. La documentazione sulla firma mostra il controllo, e il nostro articolo sulla funzione di sicurezza dei webhook spiega la configurazione.

Come recupero gli eventi che i tentativi non hanno coperto?

Anche un ricevitore perfetto perde eventi in alcuni scenari: un’interruzione più lunga della finestra dei tentativi, un firewall configurato male, un deploy che ha restituito 500 per ore. Le opzioni di recupero variano da provider a provider. Probo non offre un replay manuale e non rimette in coda le consegne fallite; si aspetta che Lei generi avvisi sugli errori e riconcili con la sua API. Stripe fa notare che gli operatori possono elaborare manualmente un arretrato per accelerare il recupero. Column afferma che eventi mancanti o aggiuntivi si possono recuperare tramite le sue API degli eventi quando i guasti richiedono una riconciliazione.

Il principio di progettazione comune, enunciato con chiarezza dalla documentazione per sviluppatori di ThriveDesk, è trattare i webhook come notifiche e non come unico registro degli eventi. Conservi i payload in modo durevole, li elabori in modo asincrono e riconcili periodicamente i record critici con l’API REST.

Un job di riconciliazione può essere piccolo:

1. A intervalli, elenchi dall’API del provider gli oggetti che contano (pagamenti, wallet, ordini) relativi all’ultima finestra temporale.
2. Confronti il loro stato con i Suoi registri.
3. Applichi le differenze attraverso lo stesso percorso di codice idempotente usato dal gestore dei webhook.
4. Imposti un avviso se il job trova lacune frequenti, perché ciò indica un problema dell’endpoint.

Poiché un evento successivo porta spesso lo stato completo e attuale di un oggetto, un evento intermedio mancato potrebbe essere comunque sovrascritto dal successivo. La riconciliazione copre i casi in cui un successivo non arriva.

Come si applicano queste garanzie agli eventi di pagamento crypto?

I pagamenti on-chain alzano la posta, perché un evento mancato o duplicato è un accredito mancato o duplicato. Alcune abitudini aiutano indipendentemente dal provider:

• Associ gli accrediti agli identificativi on-chain. Usi l’hash della transazione più l’indice del trasferimento al suo interno, non solo l’ID di consegna del webhook.
• Modelli lo stato come una progressione. In sospeso, confermato e finale sono stati con un ordine. Non lasci mai che uno stato più vecchio sovrascriva uno più recente.
• Confronti con i Suoi dati. Cerchi l’indirizzo ricevente o il riferimento nel Suo database prima di accreditare; ignori gli eventi relativi a indirizzi che non possiede.
• Riconcili i saldi. Un confronto pianificato del Suo registro con i saldi dei wallet dall’API individua tutto ciò che il flusso di eventi ha perso.

La nostra guida su come elaborare automaticamente i depositi con i webhook inserisce questi passaggi in un flusso di pagamento, e la guida ai webhook Polygon mostra l’alternativa basata su eventi al polling su una catena specifica.

La nostra prospettiva

Costruiamo webhook per sviluppatori che spostano denaro, quindi pensiamo alle garanzie di consegna ogni giorno. La nostra opinione è che nessun provider onesto possa promettere la consegna esattamente una volta, e che la risposta giusta sia un contratto pulito: gli eventi sono notifiche, le richieste firmate dimostrano da dove provengono, e l’API è sempre lì come fonte di verità.

Per questo abbiniamo le notifiche di eventi in tempo reale a un’API REST unificata su più catene. I webhook Le dicono che qualcosa è accaduto. L’API Le permette di confermarlo, di recuperare i dati decodificati delle transazioni e di riconciliare quando serve. I nostri webhook sono firmati con HMAC, così il Suo ricevitore può verificarli, e il payload contiene mittente, destinatario, contratto del token e importo già decodificati, così il Suo gestore dedica il tempo alla logica di business invece di analizzare log grezzi.

Riteniamo anche che i team non debbano gestire nodi propri né destreggiarsi tra endpoint specifici di ogni catena per arrivarci. Un’integrazione, uno schema di firma e un modo unico di consultare lo stato su Ethereum, Bitcoin, Tron, Solana, Polygon, BNB Chain e Arbitrum significano meno punti in cui può nascondersi un caso limite di consegna.

Bitblade

Costruisca su webhook firmati e multi-chain

Se sta aggiungendo pagamenti crypto a un’app, i Chaingateway Webhooks consegnano notifiche di eventi blockchain con firme HMAC, supportati da un’unica Blockchain API per wallet, trasferimenti, transazioni decodificate e prezzi del gas. I piani nella pagina dei prezzi partono da 49 € al mese per Plus, con Pro a 99 €, Premium a 249 € ed Enterprise a 499 € al mese, oppure con fatturazione annuale da 490 €.

Abbini il flusso dei webhook allo schema di riconciliazione descritto sopra, e otterrà notifiche rapide con una rete di sicurezza.

Fonti

• Adobe I/O Events FAQ
• Column: Events and Webhooks
• Wise Platform: Event ordering
• Probo Docs: Webhook Delivery and Recovery
• Stripe Documentation: Webhooks
• NestJS: Webhooks
• ThriveDesk Developer Docs: Retries, failures, and replay

Consigliati

• Webhooks vs WebSockets for Developers: Ingest, Queue, Fan Out Pattern
• The Use of Webhooks to Process Deposits Automatically
• New Feature to Enhance Webhook Security
• Polygon Webhooks: Get Real-Time On-Chain Events Without Polling