Usar webhooks com assinaturas

Saiba como usar webhooks para receber notificações de atividade de assinatura.

Você recebe notificações do aplicativo por meio de eventos de webhook da Stripe. Use eventos de webhook para gerenciar assinaturas, pois a maioria das atividades ocorre de forma assíncrona. Processe esses eventos em um endpoint de webhook ou em outros destinos, como o Amazon EventBridge, criando um destino de evento.

Para usar webhooks com suas assinaturas:

Crie um endpoint de webhook no aplicativo.
Registrar seu endpoint de webhook no Workbench
Adicione lógica para gerenciar eventos da Stripe. Para assinaturas, esses dados incluem falhas de pagamento e mudanças no estado de assinaturas (como mudar de avaliação para um estado ativo). Você pode usar o início rápido de webhooks para criar um endpoint mínimo de webhook.
Teste o endpoint de webhook para confirmar se funciona da forma esperada.

Se seu aplicativo for executado na AWS, você poderá configurar a Stripe para enviar eventos diretamente ao AWS EventBridge em sua conta da AWS.

Eventos de assinatura

A Stripe aciona eventos sempre que uma assinatura é criada ou alterada. Alguns eventos são enviados imediatamente quando a assinatura é criada, mas outros se repetem em intervalos de faturamento regulares.

Verifique se a integração gerencia adequadamente os eventos. Por exemplo, você pode enviar um e-mail para o cliente quando um pagamento falha ou revogar o acesso dele quando uma assinatura é cancelada.

A tabela a seguir descreve os eventos mais comuns relacionados a assinaturas e sugere ações para gerenciar os eventos, quando for o caso.



`customer.created`	Enviado quando um Customer é criado.
`customer.subscription.created`	Enviado quando a assinatura é criada. O `status` da assinatura pode ser `incomplete` se a autenticação do cliente for necessária para concluir o pagamento ou se você definir `payment_behavior` como `default_incomplete`. Para saber mais, consulte o comportamento do pagamento da assinatura.
`customer.subscription.deleted`	Enviado quando a assinatura do cliente termina.
`customer.subscription.paused`	Enviado quando o `status` de uma assinatura muda para `paused`. Por exemplo, isso é enviado quando uma assinatura é configurada para ser suspensa ao final de uma avaliação gratuita sem forma de pagamento. O faturamento só ocorre quando a assinatura é retomada. Não enviamos esse evento se o recebimento de pagamentos for suspenso porque as faturas continuam sendo criadas durante esse período.
`customer.subscription.resumed`	Enviado quando uma assinatura com status `paused` é retomada. Não se aplica quando a cobrança do pagamento é reiniciada.
`customer.subscription.trial_will_end`	Enviado três dias antes do final do período de avaliação. O evento é acionado quando o período de avaliação é inferior a três dias.
`customer.subscription.updated`	Enviado quando uma assinatura inicia ou é alterada. Por exemplo, o evento é acionado ao renovar uma assinatura, adicionar cupons, aplicar descontos, incluir itens de fatura ou alterar planos.
`entitlements.active_entitlement_summary.updated`	Enviado quando os direitos ativos de um cliente são atualizados. Quando receber esse evento, você pode provisionar ou cancelar o acesso aos recursos do produto. Leia mais sobre integração com direitos.
`invoice.created`	Enviado quando uma fatura é criada para uma assinatura nova ou em renovação. Se a Stripe não receber uma resposta positiva para `invoice.created`, a finalização de todas as faturas com cobrança automática será adiada por até 72 horas. Leia mais sobre a finalização de faturas. Responda à notificação enviando uma solicitação para a API finalizar uma fatura.
`invoice.finalized`	Enviado quando uma fatura é finalizada e está pronta para pagamento. Você pode enviar a fatura ao cliente. Para saber mais, consulte finalização de faturas. Dependendo da configuração, cobraremos automaticamente a forma de pagamento padrão ou tentaremos fazer a cobrança. Para saber mais, consulte e-mails após a finalização.
`invoice.finalization_failed`	Não foi possível finalizar a fatura. Leia o guia para saber como gerenciar falhas de finalização de faturas. Saiba mais sobre a finalização de faturas no guia de visão geral de faturas. Inspecione last_finalization_error da fatura para determinar a causa do erro. Se você usa o Stripe Tax, confira o campo automatic_tax do objeto Invoice. Se `automatic_tax[status]=requires_location_inputs`, não é possível finalizar a fatura e cobrar os pagamentos. Notifique o cliente e colete a localização do cliente obrigatória. Se `automatic_tax[status]=failed`, tente a solicitação outra vez mais tarde.
`invoice.paid`	Enviado quando a fatura é paga. Você pode provisionar acesso ao produto quando recebe este evento e `status` é `active`.
`invoice.payment_action_required`	Enviado quando a fatura exige autenticação do cliente. Saiba como gerenciar a assinatura quando a fatura exigir ação.
`invoice.payment_failed`	Houve uma falha no pagamento de uma fatura. O status do PaymentIntent muda para `requires_action`. O status da assinatura continua `incomplete` somente na primeira fatura da assinatura. Você pode tomar várias providências quando um pagamento falha: Avise o cliente. Saiba como configurar a assinatura para ativar o Smart Retries e outros recursos de recuperação de receitas. Se você usa PaymentIntents, colete os novos dados de pagamento e confirme o PaymentIntent. Atualize a forma de pagamento padrão na assinatura.
`invoice.upcoming`	Enviado alguns dias antes da renovação da assinatura. O número de dias é baseado no número definido para Próximos eventos de renovação no Dashboard. Para assinaturas existentes, a alteração do número de dias entra em vigor no próximo período de cobrança. Se necessário, você ainda pode adicionar outros itens de fatura.
`invoice.updated`	Enviado quando um pagamento é bem-sucedido ou falha. Se o pagamento for bem-sucedido, o atributo `paid` será definido como `true`, e `status` será `paid`. Se o pagamento falhar, `paid` será definido como `false`, e `status` permanecerá `open`. As falhas de pagamento também acionam um evento `invoice.payment_failed`.
`payment_intent.created`	Enviado quando um PaymentIntent é criado.
`payment_intent.succeeded`	Enviado quando um PaymentIntent conclui um pagamento.
`subscription_schedule.aborted`	Enviado quando um cronograma de assinatura é cancelado porque o pagamento inadimplente encerrou a assinatura relacionada.
`subscription_schedule.canceled`	Enviado quando um cronograma de assinatura é cancelado, o que também cancela qualquer assinatura associada ativa.
`subscription_schedule.completed`	Enviado quando todas as fases de um cronograma de assinatura são concluídas.
`subscription_schedule.created`	Enviado quando um novo cronograma de assinatura é criado.
`subscription_schedule.expiring`	Enviado 7 dias antes da data de vencimento de um cronograma de assinatura.
`subscription_schedule.released`	Enviado quando um cronograma de assinatura é lançado ou interrompido e dissociado da assinatura, que permanece.
`subscription_schedule.updated`	Enviado quando uma programação de assinatura é atualizada.

Gerenciar falhas de pagamento

Os eventos são uma maneira confiável de a Stripe notificar você sobre falhas nos pagamentos de faturas de assinaturas. Algumas falhas de pagamento são temporárias. Por exemplo, um emissor de cartão pode recusar a cobrança inicial, mas permitir uma nova tentativa automática. Outras falhas de pagamento são finais e exigem alguma ação, como não ter uma forma de pagamento utilizável para o cliente.

Evento Descrição

Evento	Descrição
`invoice.payment_failed`	Houve uma falha no pagamento de uma fatura. O status do PaymentIntent muda para `requires_payment_method`. O status da assinatura muda para `incomplete`. Você pode tomar várias providências quando um pagamento falha: Avise o cliente. Se você usa PaymentIntents, colete os novos dados de pagamento e confirme o PaymentIntent. Atualize a forma de pagamento padrão na assinatura. Considere a ativação de Smart Retries.

invoice.payment_failed

Houve uma falha no pagamento de uma fatura. O status do PaymentIntent muda para requires_payment_method. O status da assinatura muda para incomplete. Você pode tomar várias providências quando um pagamento falha:

Avise o cliente.
Se você usa PaymentIntents, colete os novos dados de pagamento e confirme o PaymentIntent.
Atualize a forma de pagamento padrão na assinatura.
Considere a ativação de Smart Retries.

Gerenciar pagamentos que precisam de medidas adicionais

Algumas formas de pagamento podem exigir mais etapas para sua conclusão, como autenticação do cliente. Quando recebe esses eventos, o aplicativo precisa notificar o cliente para concluir a ação necessária. Para saber como gerenciar eventos que exigem ação adicional, leia o guia de visão geral de assinaturas.

Evento Descrição

Evento	Descrição
`invoice.finalization_failed`	Não foi possível finalizar a fatura. Descubra como gerenciar falhas de finalização de faturas. Saiba mais sobre a finalização de faturas no guia de visão geral de faturas. Inspecione last_finalization_error da fatura para determinar a causa do erro. Se você usa o Stripe Tax, confira o campo automatic_tax do objeto Invoice. Se `automatic_tax[status]=requires_location_inputs`, não é possível finalizar a fatura e cobrar os pagamentos. Notifique o cliente e colete a localização do cliente obrigatória. Se `automatic_tax[status]=failed`, tente a solicitação novamente mais tarde.
`invoice.payment_failed`	Houve uma falha no pagamento de uma fatura. O status do PaymentIntent muda para `requires_action`. O status da assinatura muda para `incomplete`. Você pode tomar várias providências quando um pagamento falha: Avise o cliente. Se você usa PaymentIntents, colete os novos dados de pagamento e confirme o PaymentIntent. Atualize a forma de pagamento padrão na assinatura. Considere a ativação de Smart Retries.
`invoice.payment_action_required`	Houve uma falha no pagamento de uma fatura. O status do PaymentIntent muda para `requires_action`. O status da assinatura muda para `incomplete`. Você pode tomar várias providências quando um pagamento falha: Avise o cliente. Se você usa PaymentIntents, colete os novos dados de pagamento e confirme o PaymentIntent. Atualize a forma de pagamento padrão na assinatura. Considere a ativação de Smart Retries.

invoice.finalization_failed

Não foi possível finalizar a fatura. Descubra como gerenciar falhas de finalização de faturas. Saiba mais sobre a finalização de faturas no guia de visão geral de faturas.

Inspecione last_finalization_error da fatura para determinar a causa do erro.
Se você usa o Stripe Tax, confira o campo automatic_tax do objeto Invoice.
Se automatic_tax[status]=requires_location_inputs, não é possível finalizar a fatura e cobrar os pagamentos. Notifique o cliente e colete a localização do cliente obrigatória.
Se automatic_tax[status]=failed, tente a solicitação novamente mais tarde.

invoice.payment_failed

Houve uma falha no pagamento de uma fatura. O status do PaymentIntent muda para requires_action. O status da assinatura muda para incomplete. Você pode tomar várias providências quando um pagamento falha:

Avise o cliente.
Se você usa PaymentIntents, colete os novos dados de pagamento e confirme o PaymentIntent.
Atualize a forma de pagamento padrão na assinatura.
Considere a ativação de Smart Retries.

invoice.payment_action_required

Avise o cliente.
Se você usa PaymentIntents, colete os novos dados de pagamento e confirme o PaymentIntent.
Atualize a forma de pagamento padrão na assinatura.
Considere a ativação de Smart Retries.

Acompanhe as assinaturas ativas

As assinaturas exigem coordenação entre seu site e a Stripe — o sucesso ou falha dos pagamentos recorrentes de um cliente determinam a continuidade do acesso ao produto ou serviço.

Nas integrações comuns, quando um cliente faz uma assinatura, você armazena as credenciais dele e um valor de carimbo de data e hora com a data de validade do acesso dele ao seu site. Quando o cliente faz login, você verifica se o carimbo de data e hora ainda está no futuro. Se estiver, a conta está ativa e o cliente ainda tem acesso ao serviço.

Quando a assinatura é renovada, a Stripe cobra o cliente e tenta cobrar o pagamento cobrando automaticamente a forma de pagamento cadastrada ou enviando a fatura por e-mail aos clientes. A Stripe notifica seu site sobre o status da fatura enviando um evento de webhook:

Seu site recebe um evento invoice.paid.
- Quando cobramos automaticamente uma forma de pagamento, seu site recebe primeiro um evento invoice.upcoming no endpoint de webhook configurado alguns dias antes da renovação. É possível escutar esse evento para adicionar itens à próxima fatura. Se collection_method=send_invoice, a Stripe não envia um evento invoice.upcoming.
Seu aplicativo encontra o cliente para o qual o pagamento acabou de ser feito.
Seu aplicativo atualiza a data de validade do acesso do cliente no seu banco de dados para a data futura apropriada (mais um dia ou dois para ter uma margem).

Capturar alterações de status de assinaturas

Verifique se a integração monitora e gerencia adequadamente as transições entre os status de assinatura descritos na tabela a seguir.

Algumas mudanças de status exigem atenção especial:

Alguns dias antes do término da avaliação e da mudança da assinatura de trialing para active, você recebe um evento customer.subscription.trial_will_end. Quando você receber esse evento, verifique se o cliente tem uma forma de pagamento cadastrada e efetue a cobrança. Se preferir, avise o cliente sobre isso.
Quando uma assinatura muda para past_due, avise o cliente e solicite a atualização dos dados de pagamento. A Stripe oferece vários recursos que ajudam a automatizar esse processo. Saiba mais sobre a recuperação de receitas.
Quando uma assinatura mudar para canceled ou unpaid, revogue o acesso ao seu produto.

Status	Descrição
`trialing`	A assinatura está em período de avaliação e você pode fornecer seu produto com segurança para o cliente. A assinatura muda automaticamente para `active` quando o cliente faz o primeiro pagamento.
`active`	a assinatura está adimplente. Para assinaturas `past_due`, pagar a fatura associada mais recente ou marcá-la como incobrável faz a assinatura mudar para `active`. `active` não indica que todas as faturas pendentes associadas à assinatura foram pagas. Você pode deixar outras faturas pendentes abertas para pagamento, marcá-las como incobráveis ou anulá-las como achar melhor.
`incomplete`	O cliente precisa fazer um pagamento em até 23 horas para ativar a assinatura. Ou o pagamento demanda atenção, como autenticação do cliente. As assinaturas também podem ficar `incomplete` se houver um pagamento pendente e o status do PaymentIntent for `processing`.
`incomplete_expired`	O pagamento inicial da assinatura falhou e o cliente não concretizou o pagamento em 23 horas após a criação da assinatura. Essas assinaturas não cobram os clientes. Esse status existe para que você acompanhe os clientes que não ativaram as assinaturas.
`past_due`	O pagamento da fatura finalizada mais recente falhou ou não foi tentado. A assinatura continua gerando faturas. As configurações da assinatura determinam o próximo estado da assinatura. Se a fatura não for paga após todas as tentativas do Smart Retries, você pode configurar a assinatura para mudar para `canceled`, `unpaid` ou deixá-la como `past_due`. Para reativar a assinatura, peça ao cliente que pague a fatura mais recente. O status da assinatura muda para `active`, independentemente de o pagamento ser feito antes ou depois da data de vencimento da última fatura.
`canceled`	A assinatura foi cancelada. Durante o cancelamento, a cobrança automática de todas as faturas não pagas é desativada (`auto_advance=false`). Este estado é terminal e não pode ser atualizado.
`unpaid`	A fatura mais recente não foi paga, mas a assinatura continua ativa. A última fatura está aberta e as faturas continuam a ser geradas, mas não são feitas tentativas de pagamento. Suspensa o acesso ao seu produto quando a assinatura estiver `unpaid`, porque as tentativas de pagamento já foram feitas enquanto estava em `past_due`. Para colocar a assinatura no modo `active`, pague a fatura mais recente antes do vencimento.
`paused`	A período de avaliação da assinatura terminou sem uma forma de pagamento padrão e o trial_settings.end_behavior.missing_payment_method está definido como `pause`. Não são criadas mais faturas para a assinatura. Após vincular uma forma de pagamento padrão ao cliente, você pode reiniciar a assinatura.

Endpoints de webhooks e faturas

Registre um endpoint de webhook para acompanhar os status das faturas. Sua integração de assinaturas depende da finalização correta das faturas e do gerenciamento adequado de falhas de finalização de faturas.

Quando você habilita a cobrança automática, a Stripe automaticamente finaliza e começa a cobrança automática da fatura.

Se a Stripe não receber uma resposta adequada para invoice.created, a finalização de todas as faturas com cobrança automática é adiada por até 72 horas, exceto aquelas em que você definir um horário de finalização agendado personalizado.
Uma resposta adequada para invoice.created inclui gerenciar todos os endpoints de webhook configurados na sua conta e de todas as plataformas às quais você está conectado. Isso não inclui nenhum endpoint de webhook configurado em uma organização. Embora você possa escutar invoice.created na organização, uma resposta bem-sucedida não afeta a finalização da fatura ao usar cobrança automática.
Uma atualização de assinatura que cause uma tentativa de pagamento síncrono (na fatura inicial e em alguns tipos de atualização) não gera essa espera.
Uma falha na finalização da fatura evita a cobrança do pagamento da fatura. Certifique-se de ouvir o evento invoice.finalization_failed no seu endpoint de webhook.

Veja uma lista completa de tipos de evento de fatura.

Evento	Descrição
`invoice.created`	A fatura foi criada e está pronta para ser finalizada. Leia a documentação para saber mais sobre a finalização de faturas. Responda à notificação enviando uma solicitação à API Finalize an invoice.
`invoice.finalized`	A fatura foi finalizada e está pronta para o pagamento. Você pode enviar a fatura ao cliente. Leia mais sobre a finalização de faturas. Dependendo da configuração, a Stripe cobra automaticamente a forma de pagamento padrão ou tenta fazer a cobrança. Leia mais sobre os e-mails após a finalização.
`invoice.finalization_failed`	Não foi possível finalizar a fatura. Descubra como gerenciar falhas de finalização de faturas lendo o guia. Saiba mais sobre a finalização de faturas no guia de visão geral de faturas. Inspecione last_finalization_error da fatura para determinar a causa do erro. Se você usa o Stripe Tax, confira o campo automatic_tax do objeto Invoice. Se `automatic_tax[status]=requires_location_inputs`, não é possível finalizar a fatura e cobrar os pagamentos. Notifique o cliente e colete a localização do cliente obrigatória. Se `automatic_tax[status]=failed`, tente a solicitação outra vez mais tarde.

Finalização da fatura

A Stripe aguarda uma hora após receber uma resposta positiva para o evento invoice.created antes de tentar fazer um pagamento. Se não recebermos uma resposta positiva em 72 horas, tentaremos finalizar e enviar a fatura.

Caso você deseje tratar faturas avulsas de forma diferente das faturas de assinatura, verifique a propriedade subscription no corpo do webhook. Ela indica se a fatura foi criada para uma assinatura.

No modo de produção, se o seu endpoint de webhook não responder corretamente, a Stripe continuará tentando realizar a notificação do webhook por até três dias com um recuo exponencial. Em uma área restrita, realizamos três tentativas em algumas horas. Nesse período, não tentaremos cobrar o cliente se não recebermos uma resposta bem-sucedida. Também notificaremos você por e-mail se houver falha no webhook.

Esse comportamento se aplica a todos os endpoints de webhook definidos na sua conta, incluindo casos em que um aplicativo Connect ou outro serviço de terceiros está tendo problemas para gerenciar os webhooks de entrada.

Falha na finalização da fatura

Quando não consegue finalizar uma fatura, a Stripe envia um evento invoice.finalization_failed ao endpoint de webhook. As assinaturas permanecem ativas quando não é possível finalizar as faturas, ou seja, os usuários podem continuar acessando o produto, mesmo que você não consiga cobrar os pagamentos. Lembre-se de tomar providências para faturas com falha de finalização. Não é possível cobrar pagamentos de uma fatura não finalizada.

Para determinar a causa da falha de finalização da fatura, examine o campo last_finalization_error do objeto Invoice, que oferece mais informações sobre a falha, incluindo orientações sobre como proceder.

Se estiver usando o Stripe Tax, verifique se o campo automatic_tax.status é requires_location_inputs, indicando que os dados do endereço são inválidos ou insuficientes. Se o Stripe Tax não encontrar uma localização de cliente reconhecida, não conseguiremos finalizar a fatura. Saiba como gerenciar falhas de finalização de faturas.

Testes

Para testar o endpoint do webhook ou o destino do evento, escolha uma destas duas opções:

Execute ações em uma área restrita que enviem eventos legítimos ao destino do evento. Por exemplo, para acionar o evento charge.succeeded, você pode usar um cartão de teste que gera uma cobrança bem-sucedida.
Acione eventos usando o Stripe CLI ou usar o Stripe para Visual Studio Code.