Un cliente paga un ordine, ma il tuo sistema non lo registra perché il server era momentaneamente sovraccarico. Oppure lo registra due volte, perché il servizio di pagamento ha ritentato l’invio della notifica. Questi sono i problemi reali che nascono quando due sistemi si parlano tramite webhook, e sono più comuni di quanto si pensi. Progettare integrazioni affidabili tra applicazioni — un gestionale che riceve conferme di pagamento, un CRM che si sincronizza con un e-commerce, un software che notifica un altro sistema aziendale — richiede attenzione a due concetti che raramente vengono spiegati alle aziende, ma che fanno la differenza tra un’integrazione solida e una fonte di problemi silenziosi: idempotenza e retry.
Cosa può andare storto in un’integrazione via webhook
Un webhook è una notifica che un sistema invia a un altro quando succede qualcosa: un pagamento confermato, un nuovo ordine, un documento firmato. Sulla carta è semplice. Nella pratica, la rete non è affidabile al 100%: una richiesta può arrivare in ritardo, può fallire per un timeout, può arrivare due volte perché il mittente non ha ricevuto conferma della prima. Se il sistema che riceve il webhook non è progettato per gestire questi casi, il risultato è ordini duplicati, pagamenti contati due volte, notifiche perse o dati disallineati tra due piattaforme che dovrebbero essere sincronizzate.
Idempotenza: la stessa richiesta, ricevuta più volte, non deve fare danni
Un’operazione è idempotente quando eseguirla una volta o dieci volte produce lo stesso risultato. Per un endpoint che riceve webhook, questo si traduce in scelte tecniche precise:
- Chiave di idempotenza: ogni evento in arrivo porta un identificativo univoco (l’ID della transazione, dell’ordine, del documento). Prima di processarlo, verifico se quella chiave è già stata gestita: se sì, rispondo con successo senza rieseguire la logica.
- Transazioni atomiche sul database: la scrittura dello stato “evento processato” e l’aggiornamento dei dati (es. lo stato dell’ordine) avvengono nella stessa transazione, così non si crea una finestra in cui un evento duplicato può passare.
- Validazione della firma: verifico sempre la firma crittografica del webhook (quasi tutti i provider seri, da Stripe ai gateway di pagamento italiani, la forniscono) per essere certo che la richiesta arrivi davvero dal sistema mittente e non sia stata falsificata.
Retry: cosa fare quando una notifica non arriva a destinazione
Se il mio sistema deve notificare un altro servizio (ad esempio avvisare un CRM quando un cliente completa un acquisto) e quel servizio non risponde, non posso semplicemente perdere l’evento. La soluzione è una coda con retry automatico:
- Backoff esponenziale: se il primo tentativo fallisce, riprovo dopo pochi secondi, poi dopo qualche minuto, poi dopo ore, invece di martellare un servizio già in difficoltà.
- Dead letter queue: dopo un numero massimo di tentativi falliti, l’evento non viene scartato ma spostato in una coda separata, visibile e ripristinabile manualmente, così nessun dato si perde silenziosamente.
- Monitoraggio e alert: se gli eventi falliti superano una soglia, ricevo una notifica prima che il problema diventi visibile al cliente finale.
Come lo applico nei progetti che sviluppo
Quando costruisco integrazioni per applicazioni come apicco.app o tandemops.app — dove sistemi diversi devono scambiarsi dati in modo affidabile, dalle conferme di pagamento alle sincronizzazioni con servizi esterni — uso una coda di lavoro (worker asincroni con Redis o un database relazionale come storage delle chiavi di idempotenza) separata dal flusso principale della richiesta HTTP. Questo significa che l’utente riceve una risposta immediata, mentre l’elaborazione effettiva dell’evento avviene in background con tutte le garanzie di affidabilità descritte sopra. È lo stesso principio architetturale che applico gestendo l’infrastruttura su HestiaCP per i clienti che seguo: niente deve dipendere dalla fortuna che una singola richiesta di rete vada a buon fine al primo colpo.
Perché questo conta per un’azienda, non solo per uno sviluppatore
Un ordine duplicato, un pagamento contato due volte o una notifica persa non sono solo bug tecnici: sono soldi, tempo del team a rimediare manualmente, e in alcuni casi la fiducia di un cliente. Investire in un’integrazione progettata bene, con idempotenza e retry gestiti fin dall’inizio, costa poco rispetto al tempo che si risparmia non dovendo inseguire discrepanze tra sistemi mesi dopo il lancio.
Integrazioni su misura, affidabili fin dal primo giorno
Se la tua azienda ha bisogno di collegare sistemi diversi — un e-commerce con un gestionale, un CRM con la fatturazione, un software interno con un servizio esterno — posso progettare l’integrazione pensando fin da subito a cosa succede quando qualcosa va storto, non solo a quando tutto funziona. È il tipo di dettaglio che si nota solo quando manca.
Parliamone: https://cornelcaba.com/os-contact/. Scopri anche gli altri progetti che sviluppo e gestisco su cornelcaba.com.
