Quali webhook di Stripe seguire per il churn, e cosa significa ciascuno

La Dashboard di Stripe ti mostra gli abbonamenti come sono adesso. L’analisi del churn ha bisogno della storia di come ci sono arrivati: quando è stata chiesta una disdetta, quando ha avuto effetto, se è seguita a un pagamento fallito, se il cliente aveva prima messo in pausa. Quella storia vive negli eventi webhook, e se non li salvi man mano che arrivano, non potrai ricostruirla in seguito con molta sicurezza.

Questa guida elenca gli eventi Stripe che contano per il churn, cosa significa ciascuno e cosa salvare. Si attiene alla guida di Stripe using webhooks with subscriptions, alla panoramica dei webhook, al riferimento API cancel subscription, al riferimento Early Fraud Warning e all’articolo di supporto di Stripe sul card updater (tutti consultati a novembre 2026).

L’elenco breve

Evento	Cosa significa per il churn
customer.subscription.created	È partito un abbonamento. Non è la prova di un pagamento.
customer.subscription.updated	Qualcosa è cambiato: piano, coupon, rinnovo, una disdetta programmata, una pausa dell’incasso
customer.subscription.deleted	L’abbonamento è terminato. Questo è l’evento di churn.
customer.subscription.paused	Lo stato è passato a paused
customer.subscription.resumed	Un abbonamento in pausa è ripartito
customer.subscription.trial_will_end	Una prova sta per finire
invoice.payment_failed	Un tentativo di pagamento è fallito
invoice.paid	Una fattura è stata pagata, anche dopo un fallimento
payment_method.automatically_updated	Il card updater ha sostituito i dati della carta
charge.dispute.created	Un cliente ha contestato un addebito
radar.early_fraud_warning.created	Un emittente ha segnalato un addebito come possibile frode

Il resto della guida li passa in rassegna nell’ordine in cui di solito avvengono.

Inizio e modifiche

customer.subscription.created

Stripe lo invia quando viene creato un abbonamento. È l’inizio dei tuoi dati di coorte, ma non prova che il cliente abbia pagato. Se la prima fattura fallisce, la guida ai webhook dice che l’abbonamento resta incomplete. Salva la data di creazione, ma conta un cliente come acquisito solo quando la prima fattura è pagata.

customer.subscription.updated

Stripe descrive questo evento come inviato quando un abbonamento parte o cambia: rinnovo, aggiunta di un coupon, applicazione di uno sconto, aggiunta di una voce di fattura e cambio di piano lo fanno scattare tutti. Per il churn, contano soprattutto tre modifiche al suo interno:

1. Viene programmata una disdetta. Quando cancel_at_period_end diventa true, il cliente ha deciso di andarsene, anche se l’abbonamento è ancora attivo. Salva questa data. È il momento della decisione, che può arrivare settimane prima della fine dell’abbonamento.
2. Viene annullata una disdetta. Quando cancel_at_period_end torna false, hai tenuto il cliente. Salva anche questo, o i tuoi salvataggi resteranno invisibili.
3. Un downgrade. Un cambio di piano verso un prezzo più basso è contrazione, il cugino silenzioso del churn.

Poiché questo evento scatta per molti motivi, confronta il nuovo oggetto con previous_attributes nell’evento per vedere cosa è cambiato davvero.

La fine

customer.subscription.deleted

La guida ai webhook lo dice chiaramente: inviato quando l’abbonamento di un cliente termina. Questo è il tuo evento di churn. Il suo timestamp è il momento in cui i ricavi si sono fermati.

Leggi cancellation_details sull’abbonamento, documentato nel riferimento API cancel:

• reason ti dice perché è terminato: cancellation_requested, payment_failed o payment_disputed, tra gli altri. È così che separi il churn volontario da quello involontario senza tirare a indovinare.
• feedback contiene il motivo scelto dal cliente, come too_expensive, unused, missing_features o switched_service.
• comment contiene il testo libero scritto dal cliente.

Se ricordi una sola cosa di questa guida, salva reason e feedback al momento della cancellazione. Per le metriche costruite sopra, vedi come calcolare il tasso di churn e churn involontario.

La pausa

customer.subscription.paused e customer.subscription.resumed

Stripe invia customer.subscription.paused quando lo stato di un abbonamento passa a paused, anche in automatico quando una prova termina senza metodo di pagamento se lo hai configurato. Invia customer.subscription.resumed quando un abbonamento in pausa riprende, e la guida segnala che non si applica quando viene tolta la pausa solo all’incasso.

La distinzione conta: una pausa dell’incasso (pause_collection) non cambia lo stato, quindi la vedi solo tramite customer.subscription.updated. Se offri pause come strumento di retention, segui entrambi i tipi. I dettagli sono in come mettere in pausa un abbonamento su Stripe.

Un cliente in pausa non ha fatto churn. Riportalo a parte, e attribuisci qualsiasi disdetta successiva al motivo originale.

Le prove

customer.subscription.trial_will_end

Stripe lo invia tre giorni prima della fine di una prova, o subito se la prova dura meno di tre giorni. È il tuo ultimo buon momento per ricordarlo al cliente, verificare che ci sia un metodo di pagamento registrato e assicurarti che abbia raggiunto la parte del prodotto che lo fa restare. Il passaggio da prova a pagamento è una metrica di churn a pieno titolo; vedi conversione da prova a pagamento.

I pagamenti

invoice.payment_failed

Un tentativo di pagamento su una fattura è fallito. Sui rinnovi questo apre la finestra di sollecito. Salva il numero del tentativo, il decline code e l’advice code da last_payment_error del PaymentIntent; la nostra guida ai decline code di Stripe spiega cosa significa ciascuno.

Non registrare il churn qui. Un pagamento fallito è un rischio, non un’uscita. L’abbonamento fa churn solo quando viene cancellato, o quando le tue impostazioni di recupero lo portano in uno stato in cui smetti di servire il cliente.

invoice.paid

La fattura è stata pagata. Dopo un fallimento, questo è il tuo evento di recupero. Salva quale tentativo è riuscito e se il cliente aveva prima cambiato carta. Nel tempo, ti dirà se il grosso del recupero lo fanno i nuovi tentativi o le email.

payment_method.automatically_updated

L’articolo di supporto di Stripe sul card updater dice che Stripe crea questo evento quando il card updater modifica i dati di una carta. Spiega un rinnovo che riesce su una carta che altrimenti sarebbe scaduta. Registrarlo ti permette di vedere quanto churn involontario il circuito evita per te; altro in carte in scadenza.

Contestazioni e frodi

charge.dispute.created

Un cliente ha contestato un addebito con la sua banca. Per il churn, una contestazione è quasi sempre la fine della relazione, e Stripe registra payment_disputed come reason della disdetta quando un abbonamento termina per questa causa. Segui le contestazioni separatamente dalle disdette: costano commissioni, e richiedono una risposta.

radar.early_fraud_warning.created

Il riferimento Early Fraud Warning lo descrive come l’emittente che notifica a Stripe che un addebito potrebbe essere fraudolento. Non è ancora una contestazione. Se vendi abbonamenti, decidi in fretta se rimborsare e fermare gli addebiti futuri. Trattiamo questa decisione in early fraud warning di Stripe.

Salvare gli eventi in modo che i numeri reggano

La panoramica dei webhook di Stripe documenta alcuni comportamenti che determinano come salvare gli eventi:

1. Gli eventi possono arrivare fuori ordine. Stripe non garantisce l’ordine di consegna. Usa il tempo created dell’evento e i campi dell’oggetto, non l’ordine di arrivo, per costruire la storia.
2. Gli eventi possono arrivare più di una volta. Deduplica sull’ID dell’evento prima di scrivere qualsiasi cosa.
3. Restituisci un 2xx in fretta. Salva l’evento grezzo, conferma la ricezione ed elaboralo in un job in background.
4. Verifica le firme. Controlla l’header Stripe-Signature con il secret del tuo endpoint prima di fidarti di un payload.

Una tabella semplice funziona bene: ID dell’evento, tipo, tempo di creazione, ID del cliente, ID dell’abbonamento e payload grezzo. Ricava da lì le tue tabelle di churn. Quando una definizione cambia, puoi ricalcolare dagli eventi grezzi invece di perdere la storia.

Cosa ricavare

• Inizio dell’abbonamento (prima fattura pagata), disdetta richiesta, disdetta annullata, fine.
• reason e feedback alla fine.
• Inizio e fine della pausa.
• Ogni pagamento fallito con i suoi codici, e il recupero che ne è seguito.
• Contestazioni ed early fraud warning per cliente.

Farlo con NoChurn

NoChurn si collega a Stripe in un clic e legge questi eventi per te, così non devi costruire da solo il salvataggio descritto sopra. Li usa per smart retry, email di recupero che controlli, risposte del flusso di disdetta, email di win-back a 30, 60 e 90 giorni e un churn score da 0 a 100. Puoi aggiungere i tuoi dati sui clienti via API. Stripe resta la fonte di verità per la fatturazione. Vedi NoChurn + Stripe.