Que webhooks do Stripe usar para acompanhar o churn, e o que significa cada um

O Dashboard do Stripe mostra-lhe as subscrições tal como estão agora. A análise do churn precisa da história de como lá chegaram: quando foi pedido um cancelamento, quando produziu efeito, se se seguiu a um pagamento falhado, se o cliente pausou primeiro. Essa história está nos eventos de webhook, e se não os guardar à medida que chegam, não a conseguirá reconstruir mais tarde com grande confiança.

Este guia enumera os eventos do Stripe que contam para o churn, o que significa cada um e o que guardar. Baseia-se no guia using webhooks with subscriptions do Stripe, na visão geral dos webhooks, na referência da API de cancelamento de subscrições, na referência Early Fraud Warning e no artigo de suporte do Stripe sobre o card updater (todos consultados em novembro de 2026).

A lista curta

Evento	O que significa para o churn
customer.subscription.created	Uma subscrição começou. Não é prova de pagamento.
customer.subscription.updated	Algo mudou: plano, cupão, renovação, um cancelamento agendado, uma pausa da cobrança
customer.subscription.deleted	A subscrição terminou. Este é o evento de churn.
customer.subscription.paused	O estado passou a paused
customer.subscription.resumed	Uma subscrição em pausa regressou
customer.subscription.trial_will_end	Um trial termina em breve
invoice.payment_failed	Uma tentativa de pagamento falhou
invoice.paid	Uma fatura foi paga, incluindo depois de uma falha
payment_method.automatically_updated	O card updater substituiu os dados do cartão
charge.dispute.created	Um cliente disputou uma cobrança
radar.early_fraud_warning.created	Um emissor sinalizou uma cobrança como possível fraude

O resto deste guia percorre-os pela ordem em que normalmente acontecem.

Começar e mudar

customer.subscription.created

O Stripe envia-o quando uma subscrição é criada. É o início dos seus dados de coorte, mas não prova que o cliente pagou. Numa primeira fatura que falha, o guia de webhooks diz que a subscrição fica incomplete. Guarde a data de criação, mas conte um cliente como adquirido apenas quando a primeira fatura for paga.

customer.subscription.updated

O Stripe descreve este evento como enviado quando uma subscrição começa ou muda: renovar, acrescentar um cupão, aplicar um desconto, acrescentar um item de fatura e mudar de plano desencadeiam-no. Para o churn, três mudanças dentro dele são as que mais contam:

1. Um cancelamento é agendado. Quando cancel_at_period_end passa a true, o cliente decidiu sair, embora a subscrição continue ativa. Guarde esta data. É o momento da decisão, que pode ser semanas antes de a subscrição terminar.
2. Um cancelamento é retirado. Quando cancel_at_period_end volta a false, manteve o cliente. Guarde isto também, ou as suas retenções ficam invisíveis.
3. Um downgrade. Uma mudança para um preço mais barato é contração, o primo discreto do churn.

Como este evento dispara por muitos motivos, compare o novo objeto com previous_attributes no evento para ver o que mudou de facto.

Terminar

customer.subscription.deleted

O guia de webhooks di-lo claramente: enviado quando a subscrição de um cliente termina. É o seu evento de churn. O seu timestamp é o momento em que a receita parou.

Leia cancellation_details na subscrição, documentado na referência da API de cancelamento:

• reason diz-lhe porque terminou: cancellation_requested, payment_failed ou payment_disputed, entre outros. É assim que separa o churn voluntário do involuntário sem adivinhar.
• feedback contém o motivo escolhido pelo cliente, como too_expensive, unused, missing_features ou switched_service.
• comment contém o texto livre que o cliente escreveu.

Se só se lembrar de uma coisa deste guia, que seja esta: guarde reason e feedback no momento da eliminação. Para os indicadores construídos por cima, veja como calcular a taxa de churn e churn involuntário.

Pausar

customer.subscription.paused e customer.subscription.resumed

O Stripe envia customer.subscription.paused quando o estado de uma subscrição passa a paused, incluindo automaticamente quando um trial termina sem meio de pagamento se o tiver configurado. Envia customer.subscription.resumed quando uma subscrição em pausa é retomada, e o guia indica que não se aplica quando apenas a cobrança deixa de estar em pausa.

Essa distinção conta: uma pausa da cobrança (pause_collection) não muda o estado, por isso só a vê através de customer.subscription.updated. Se oferece pausas como ferramenta de retenção, acompanhe os dois tipos. Os detalhes estão em como pausar uma subscrição no Stripe.

Um cliente em pausa não cancelou. Reporte-o à parte, e atribua qualquer cancelamento posterior ao motivo original.

Trials

customer.subscription.trial_will_end

O Stripe envia-o três dias antes do fim de um trial, ou de imediato se o trial durar menos de três dias. É o seu último bom momento para lembrar o cliente, verificar que há um meio de pagamento registado e garantir que chegou à parte do produto que o faz ficar. A passagem de trial a pago é um indicador de churn por direito próprio; veja conversão de trial para pago.

Pagamentos

invoice.payment_failed

Uma tentativa de pagamento de uma fatura falhou. Nas renovações, isto abre a janela de recuperação. Guarde o número da tentativa, o decline code e o advice code de last_payment_error do PaymentIntent; o nosso guia dos decline codes do Stripe explica o que significa cada um.

Não registe churn aqui. Um pagamento falhado é um risco, não uma saída. A subscrição só se perde quando é eliminada, ou quando as suas definições de recuperação a passam para um estado em que deixa de servir o cliente.

invoice.paid

A fatura foi paga. Depois de uma falha, este é o seu evento de recuperação. Guarde que tentativa foi bem-sucedida e se o cliente mudou primeiro de cartão. Com o tempo, isso diz-lhe se são as novas tentativas ou os emails que fazem a maior parte do trabalho de recuperação.

payment_method.automatically_updated

O artigo de suporte do Stripe sobre o card updater diz que o Stripe cria este evento quando o card updater altera os dados de um cartão. Explica uma renovação bem-sucedida num cartão que de outro modo teria expirado. Registá-lo permite-lhe ver quanto churn involuntário a rede evita por si; mais em cartões a expirar.

Disputas e fraude

charge.dispute.created

Um cliente disputou uma cobrança junto do banco. Para o churn, uma disputa é quase sempre o fim da relação, e o Stripe regista payment_disputed como reason de cancelamento quando uma subscrição termina por esse motivo. Acompanhe as disputas à parte dos cancelamentos: custam taxas e precisam de uma resposta.

radar.early_fraud_warning.created

A referência Early Fraud Warning descreve-o como o emissor a notificar o Stripe de que uma cobrança pode ser fraudulenta. Ainda não é uma disputa. Se vende subscrições, decida depressa se reembolsa e para as cobranças futuras. Tratamos essa decisão em early fraud warnings do Stripe.

Guardar os eventos para que os números se aguentem

A visão geral dos webhooks do Stripe documenta alguns comportamentos que determinam a forma como guarda os eventos:

1. Os eventos podem chegar fora de ordem. O Stripe não garante a ordem de entrega. Use a hora created do evento e os próprios campos do objeto, não a ordem de chegada, para construir o histórico.
2. Os eventos podem chegar mais do que uma vez. Elimine os duplicados pelo ID do evento antes de escrever o que quer que seja.
3. Devolva rapidamente um 2xx. Guarde o evento em bruto, confirme a receção e processe-o numa tarefa em segundo plano.
4. Verifique as assinaturas. Verifique o cabeçalho Stripe-Signature com o segredo do seu endpoint antes de confiar num payload.

Uma tabela simples funciona bem: ID do evento, tipo, hora de criação, ID do cliente, ID da subscrição e o payload em bruto. Derive dela as suas tabelas de churn. Quando uma definição muda, pode recalcular a partir dos eventos em bruto em vez de perder o histórico.

O que derivar

• Início da subscrição (primeira fatura paga), cancelamento pedido, cancelamento retirado, fim.
• reason e feedback no fim.
• Início e fim das pausas.
• Cada pagamento falhado com os seus códigos, e a recuperação que se seguiu.
• Disputas e early fraud warnings por cliente.

Fazer isto com o NoChurn

O NoChurn conecta-se ao Stripe com um clique e lê estes eventos por si, para que não tenha de construir o armazenamento acima. Usa-os para as novas tentativas inteligentes, os emails de recuperação que revê, as respostas do fluxo de cancelamento, os emails de reconquista aos 30, 60 e 90 dias e um score de churn de 0 a 100. Pode acrescentar os seus próprios dados de clientes pela API. O Stripe continua a ser a fonte de verdade da faturação. Veja NoChurn + Stripe.