Configura un endpoint webhook Stripe, verifica Stripe-Signature sul raw body, testa con stripe listen e stripe trigger ed evadi gli ordini Checkout una sola volta.
Un webhook Stripe è un endpoint HTTPS sul tuo server a cui Stripe invia con una POST il JSON di un evento, come checkout.session.completed dopo un pagamento. Il tuo handler deve verificare l'header Stripe-Signature sul raw body non modificato usando il secret whsec_ dell'endpoint, rispondere in fretta con un 2xx e gestire senza problemi lo stesso evento che arriva più di una volta.
Gli elementi essenziali dei webhook Stripe (verificati sulla documentazione Stripe, ottobre 2026)
La maggior parte delle integrazioni Stripe non funzionanti si rompe in uno di tre punti: il framework ha fatto il parsing del body prima della verifica, l'handler ha svolto lavoro lento ed è andato in timeout, oppure un evento ritentato ha evaso un ordine due volte. Questa guida mostra un handler che evita tutti e tre i problemi, con un verificatore qui sotto che controlla un header Stripe-Signature nel tuo browser, così vedi esattamente cosa calcola la libreria.
Quasi sempre perché il body è stato modificato prima della verifica, per esempio da express.json() o da un body parser che ricodifica il JSON. Monta express.raw({ type: "application/json" }) solo sulla route del webhook, oppure leggi request.text() in un route handler di Next.js. Anche un secret sbagliato produce lo stesso messaggio.
checkout.session.completed per i pagamenti con carta, più checkout.session.async_payment_succeeded per i metodi differiti come gli addebiti bancari. Stripe suggerisce anche di gestire checkout.session.async_payment_failed così puoi avvisare il cliente. Controlla il payment_status della sessione prima di evadere l'ordine.
No. La documentazione di Stripe stessa dice che un cliente può pagare e chiudere la scheda prima che la tua pagina di successo si carichi. Usa pure la pagina di successo per una conferma rapida, ma anche il webhook deve avviare l'evasione, ed entrambi i percorsi devono poter essere eseguiti due volte senza danni.
Stripe non garantisce l'ordine. invoice.paid può arrivare prima di customer.subscription.created. Tieni traccia degli id degli eventi per individuare i duplicati e recupera l'oggetto correlato dall'API quando ti serve il suo stato più recente.
Clicca Resend sull'evento nella Dashboard (funziona fino a 15 giorni dopo la creazione) oppure esegui stripe events resend <event_id> --webhook-endpoint=<endpoint_id> con la CLI (fino a 30 giorni). I tentativi automatici continuano in ogni caso.
express.raw è montato solo su questa route, così il body arriva a constructEvent come i byte originali.
request.text() restituisce il body senza parsing. Se constructEvent lancia un errore, la firma o il secret sono sbagliati.
listen stampa un secret whsec_ per questa sessione. Inseriscilo nel tuo env locale, poi genera eventi in un secondo terminale.
Tipi di evento Stripe comuni e cosa fare
Incolla un header Stripe-Signature, il raw body e il tuo secret whsec_ per vedere lo stesso controllo che eseguono le librerie. Gira nel tuo browser con Web Crypto e non invia nulla. Usa un secret di test, mai uno live.
Header Stripe-Signature
Raw body della richiesta
Secret dell'endpoint (whsec_...)
Tolleranza in secondi
Firma ora questo body
Verifica
Risultato
L'header non ha un timestamp t=.
L'header non ha una firma v1=.
v1 atteso: {v}
La firma corrisponde.
La firma non corrisponde: il body è stato modificato o il secret è sbagliato.
Il timestamp ha {n} secondi, entro la tolleranza.
Il timestamp ha {n} secondi, fuori dalla tolleranza: una libreria lo rifiuterebbe.
Inizia gratis · Nessuna carta di credito richiesta