Come rendere idempotenti i webhook di pagamento o WhatsApp?

Assegna a ogni webhook un ID univoco fornito dal mittente, come un ID ordine o un ID messaggio, ed esegui i suoi effetti collaterali una sola volta. Una consegna ripetuta trova l'ID già elaborato e non fa nulla. Pubblica il lavoro vero e proprio su una coda invece di eseguirlo inline, così il mittente non deve aspettare.

Perché i webhook arrivano più di una volta?

I mittenti ritentano in caso di timeout, problemi di rete o risposte non 2xx, e preferiscono consegnare due volte piuttosto che non consegnare affatto. Gateway di pagamento e WhatsApp adottano questa logica. Un gestore che agisce su ogni consegna può generare biglietti duplicati, inviare due volte una conferma di prenotazione o addebitare due volte.

Quale dovrebbe essere la chiave di idempotenza?

Usa l'identificatore che il mittente garantisce stabile tra i ritentativi: l'ID ordine per i webhook di pagamento, l'ID messaggio per WhatsApp. Memorizza le chiavi già elaborate e verifica prima di agire. Una chiave generata da te per ogni consegna non funziona, perché ogni ritentativo sembrerebbe un evento nuovo.

Perché pubblicare su una coda invece di eseguire il lavoro nel gestore?

Generare un biglietto e inviare un'email inline fa aspettare il gateway su operazioni che non gli interessano, causando timeout e ulteriori ritentativi. Conferma rapidamente, pubblica un evento di pagamento confermato su RabbitMQ e lascia che un consumer esegua il lavoro. Una consegna ripetuta pubblica una volta sola; la seconda è un'operazione nulla.

Dove viene usato questo in produzione?

Su FindYourVibe il webhook di pagamento è idempotente sull'ID ordine e pubblica su RabbitMQ prima che un consumer emetta il biglietto. Su Trexind ogni gestore webhook WhatsApp è idempotente sull'ID messaggio, così una consegna ritentata aggiorna lo stato una sola volta invece di riattivare effetti collaterali di prenotazione o fatturazione.

Come testare che un webhook sia idempotente?

Invia lo stesso payload due volte, idealmente in parallelo, e verifica che l'effetto collaterale sia avvenuto una sola volta: un biglietto, una prenotazione, un addebito. Poi riproduci un payload vecchio dopo che il primo è stato completamente processato. Se qualche conteggio supera uno, il controllo della chiave è in competizione o manca un vincolo di unicità.

Originariamente pubblicato su sakshamjain.codes/blog/idempotent-payment-and-whatsapp-webhooks. Hai bisogno di questo sviluppo? Guarda i miei servizi su NexoRush o contattami.