Webhook duplicati: come evitare due volte lo stesso ordine nel CRM
Un webhook può arrivare più volte. Come progettare retry, deduplicazione e scritture nel CRM senza duplicare ordini, notifiche e attività.
Il pagamento è riuscito, ma la risposta del tuo server si perde. Il servizio di pagamento invia di nuovo la notifica. Se ogni consegna crea un ordine nel CRM, ora hai due ordini per un solo acquisto.
La soluzione non è spegnere i tentativi automatici. È rendere l'operazione idempotente: ripetere la stessa richiesta non deve produrre un secondo effetto. Vale anche quando il flusso include un agente AI che prepara una nota, assegna un'attività o chiama un altro strumento.
Una notifica non è una consegna unica
Un webhook è una chiamata che un servizio manda al tuo sistema quando succede qualcosa. Non è una promessa che il messaggio arriverà una sola volta o nell'ordine previsto.
La documentazione Stripe descrive tentativi automatici, possibili eventi duplicati e consegne fuori ordine. Nell'ambiente live, i tentativi automatici possono continuare fino a tre giorni. Sono caratteristiche di Stripe, non regole universali: ogni integrazione va controllata nella propria documentazione.
Quindi il requisito utile non è «riceviamo ogni messaggio una volta». È «ogni pagamento confermato genera un solo ordine, anche se la notifica torna».
Esempio: dal pagamento al CRM
Immagina un flusso che registra un ordine, crea un'attività per il commerciale e manda una conferma. È un esempio progettuale, non il resoconto di un test su un cliente.
Prima di scrivere codice, definisci due identità diverse:
- L'identificativo dell'evento, per riconoscere la riconsegna dello stesso messaggio.
- La chiave dell'operazione aziendale, per riconoscere lo stesso risultato anche quando viene richiesto da eventi diversi.
Per l'ordine, una chiave potrebbe combinare account del fornitore, identificativo del pagamento e azione «crea ordine». Non usare soltanto l'email del cliente: la stessa persona può fare due acquisti legittimi.
Allo stesso modo, non fondere automaticamente tutti gli eventi relativi a un pagamento. Conferma e rimborso sono azioni diverse. La chiave deve esprimere l'intenzione, non solo l'oggetto.
Un registro che resiste ai tentativi ripetuti
Una sequenza ragionevole separa la ricezione dall'elaborazione:
- Verifica firma e autenticità del webhook secondo le istruzioni del fornitore, prima di fidarti del contenuto.
- Salva l'evento in un registro persistente, con un vincolo univoco sul suo identificativo nel contesto del fornitore e dell'account.
- Conferma la ricezione solo dopo averne assicurato la registrazione durevole. Se non riesci a salvarlo, non dichiararlo acquisito.
- Un processo separato legge gli eventi da elaborare e applica le regole aziendali.
- Registra risultato, identificativo CRM e stato di ogni effetto, per poter riprendere un lavoro interrotto.
«Prima cerco, poi creo» non basta. Due processi possono cercare contemporaneamente, non trovare nulla e creare entrambi l'ordine. Serve un vincolo univoco o una prenotazione atomica della chiave dell'operazione.
Il registro deve distinguere almeno lavoro in attesa, in corso, completato e fallito. Un evento già registrato ma non completato non va semplicemente scartato: potrebbe essere il lavoro da recuperare dopo un arresto.
Il punto difficile: il CRM ha già risposto?
Il CRM può creare l'ordine e poi la connessione può interrompersi prima che tu riceva l'identificativo. Riprovare alla cieca può duplicarlo. Segnare il lavoro come completato prima della chiamata può invece perderlo.
Se il CRM supporta una chiave di idempotenza, riusa la stessa chiave per tutti i tentativi della medesima operazione, rispettandone durata e vincoli. Altrimenti verifica se consente un identificativo esterno univoco e un aggiornamento o inserimento basato su quello.
Se nessuna delle due opzioni esiste, serve una riconciliazione: controllare lo stato esterno e risolvere i casi incerti. Non promettere un risultato «esattamente una volta» soltanto perché hai aggiunto una tabella locale.
Anche email e attività sono effetti separati. Un ordine non duplicato non garantisce una sola email. Progetta una chiave e uno stato per ciascun effetto importante. Il modello descritto da AWS sulle API idempotenti spiega perché identificare esplicitamente l'intenzione rende i retry più sicuri.
Dove entra l'AI
Un agente può classificare la richiesta o proporre il testo della conferma. Non dovrebbe decidere da solo se un pagamento sia già stato registrato sulla base della conversazione.
La memoria dell'agente non sostituisce il registro delle operazioni. Passagli uno strumento che applica i controlli sul server. Un secondo tentativo deve ritrovare l'ordine esistente, non affidarsi alla promessa «non farlo due volte» nel prompt.
Il collaudo da chiedere prima del rilascio
- Invia due volte lo stesso evento: resta un solo ordine?
- Fai arrivare due copie contemporaneamente: il vincolo regge?
- Interrompi il processo dopo la creazione nel CRM: come recuperi l'identificativo senza duplicare?
- Consegna gli eventi fuori ordine: consulti lo stato autorevole quando serve?
- Riprendi un evento fallito: completi solo gli effetti mancanti?
- Controlla conservazione del registro e finestre di retry: quanto a lungo riconosci un duplicato?
Non sono test eseguiti da Studio Futuro su questa integrazione. Sono criteri di accettazione da applicare al tuo flusso, in un ambiente di prova e con dati non sensibili.
Per partire dal processo prima degli strumenti, leggi l'audit AI per PMI. Per assegnare procedure ripetibili agli agenti, continua con le skill DevOps.
Il prossimo passo
Scegli una sola automazione e scrivi cosa deve accadere se la stessa richiesta arriva due volte. Se la risposta è «speriamo che non succeda», manca ancora una regola del sistema.
Parliamone: progettiamo un flusso con controlli e recupero degli errori.
In breve: Non basta ricevere un evento una sola volta: ogni effetto importante deve poter essere ripetuto senza creare un secondo risultato.
Newsletter
L'AI che funziona davvero, nella tua casella.
Le nuove pillole, gli strumenti che usiamo e quello che impariamo sui progetti. Poche mail, solo quando c’è qualcosa di utile.
