Receba eventos da Stripe no seu endpoint de webhook
Envie eventos para sua conta da AWS
Estamos lançando o suporte para recebimento de eventos da Stripe no Amazon EventBdge em beta privado. Para obter acesso antecipado, registre-se em event bridge.stripe.dev.
Por que usar webhooks
Quando você cria integrações com a Stripe, seus aplicativos podem precisar receber eventos à medida que ocorrem nas contas Stripe para que sistemas de backend executem as ações necessárias.
Para habilitar eventos de webhook, você precisa registrar endpoints de webhook. Depois de registrá-los, a Stripe pode enviar dados de evento em tempo real para o endpoint de webhook do aplicativo quando ocorrem eventos na sua conta Stripe. A Stripe usa HTTPS para enviar eventos de webhook ao aplicativo como um conteúdo JSON que inclui um objeto Event.
O recebimento de eventos de webhook é particularmente útil para ouvir eventos assíncronos, como quando um banco confirma um pagamento, um cliente contesta uma cobrança, um pagamento recorrente é finalizado ou no recebimento de pagamentos de assinaturas.
Visão geral do evento
A Stripe gera dados de eventos que podemos enviar para informar sobre atividades na sua conta.
Quando ocorre um evento, a Stripe gera um novoobjeto Event. Uma única solicitação de API pode resultar na criação de vários eventos. Por exemplo, se você criar uma assinatura para um cliente, receberá os eventos customer.subscription.created
e payment_intent.succeeded
.
Ao registrar endpoints de webhook em sua conta Stripe, você permite que a Stripe envie automaticamente objetos Event como parte de solicitações POST para o endpoint de webhook registrado hospedado pelo seu aplicativo. Depois que o endpoint do webhook recebe o Event, o aplicativo pode executar ações de backend (por exemplo, chamar as APIs da transportadora para agendar uma remessa após receber um evento payment_intent.succeeded
).
Objeto Event
O objeto Event que enviamos ao seu endpoint de webhook fornece um instantâneo do objeto que foi alterado. Ele pode incluir uma propriedade previous_attributes
que indica a mudança, quando for o caso.
Veja a lista completa de tipos de eventos que enviamos ao seu webhook.
Exemplo de conteúdo de evento
O evento a seguir mostra uma atualização de assinatura no final de uma avaliação.
{ "id": "evt_1MqqbKLt4dXK03v5qaIbiNCC", "object": "event", "api_version": "2024-04-10", "created": 1680064028,
Estrutura do objeto de evento
Examine a estrutura do objeto de evento para entender melhor os eventos e as informações associadas que eles fornecem.
Tipo de evento
Você recebe eventos para todos os tipos de evento ouvidos pelo endpoint de webhook na configuração. Use o type
do evento recebido para determinar qual processamento seu aplicativo precisa realizar. O data.object
de cada type
de evento varia.
Modo de produção e de teste
Nos endpoints, você pode receber solicitações de entrega de eventos no modo de produção e teste. Isso pode acontecer se você usa um único endpoint para o modo de produção e o modo de teste ou se você é uma plataforma do Connect que faz solicitações no modo de teste para contas conectadas Standard de produção. Use o atributo livemode
para verificar se o objeto existe no modo de produção ou de teste e determinar o tratamento correto para o evento.
Versão da API
A api_version
indica a versão da API do evento e determina a estrutura do data.object incluído. O endpoint recebe eventos usando a versão da API configurada, que pode ser diferente da versão da API padrão da sua conta ou de qualquer solicitação relacionada ao evento. Esse atributo é determinado pelo endpoint de destino, o que indica que o mesmo evento pode ser entregue a vários endpoints usando diferentes versões de API. Se você usa nossas bibliotecas de cliente Java, .NET ou Go, certifique-se de configurar a versão da API do endpoint para usar a mesma versão de API fixada no cliente. Caso contrário, pode ser que você não consiga desserializar os objetos de evento.
Ao recuperar objetos Event da API, não é possível controlar a versão da API da estrutura data.object
. Em vez disso, recupere esse objeto do endpoint de API apropriado e use o cabeçalho Stripe-Version
para especificar uma versão de API.
Eventos de solicitação de API
Quando uma solicitação de API gera um evento, essa solicitação aparece como o request.id
. Se você usar uma idempotency_key
ao fazer a solicitação, ela será incluída como request.idempotency_key
. Verifique o hash desse request
quando investigar o que causa um evento.
Objeto de dados e atributos anteriores
Para eventos *.updated
, o conteúdo do evento inclui data.previous_attributes
, que permite inspecionar o que mudou no objeto da Stripe . O previous_ attributes
no exemplo de evento customer.subscription.updated
acima indica que a assinatura tem um valor anterior de status: trialing
, entre outras alterações. O data.object
indica o status como active
, o que significa que a assinatura saiu de um período de avaliação.
Entregas pendentes
Use pending_webhooks
para determinar quantos endpoints configurados para este evento não responderam corretamente à entrega. Durante a entrega inicial, esse valor é 1 ou mais porque o endpoint não respondeu corretamente. Se você recuperar esse evento mais tarde, pending_webhooks
diminuirá para um mínimo de 0 à medida que cada endpoint responder corretamente. Isso é importante para eventos invoice.created
porque entregas malsucedidas podem atrasar a finalização da fatura.
Eventos de contas conectadas
Os eventos de contas conectadas entregues a um endpoint do Connect incluem a account
. Use account
para rastrear a qual conta conectada o objeto pertence e garantir que a plataforma possa processar os dados do evento corretamente.
Por que são gerados os objetos de evento
Esta tabela descreve diferentes cenários que acionam a geração de objetos Event.
Origem | Acionador |
---|---|
Dashboard | Quando você chama uma API modificando seus recursos da Stripe no Stripe Dashboard. |
API | Quando uma ação do usuário no aplicativo ou site resulta em uma chamada de API. |
API | Quando você aciona manualmente um evento com a Stripe CLI. |
API | Quando você chama uma API diretamente com a Stripe CLI. |
Comece já
Para começar a receber eventos de webhook no aplicativo, crie e registre um endpoint de webhook seguindo as etapas abaixo:
- Crie um gerenciador de endpoint de webhook para receber solicitações POST de dados de evento.
- Teste o gerenciador de endpoints de webhook localmente usando a Stripe CLI.
- Registre seu endpoint na Stripe usando o Dashboard ou a API.
- Proteja o endpoint do webhook.
Você pode registrar e criar um endpoint para processar vários tipos de evento ao mesmo tempo ou configurar endpoints individuais para eventos específicos.
Criar um gerenciador
Configure uma função de HTTP ou HTTPS que aceite solicitações de webhooks com um método POST. Se você ainda está desenvolvendo a função de endpoint em uma máquina local, pode ser HTTP. Quando o endpoint for público, terá de ser HTTPS.
Configure sua função de endpoint para:
- Processe solicitações POST com um conteúdo JSON que consiste em um objeto de evento.
- Retorne rapidamente um código de status de êxito (
2xx
) antes de qualquer lógica complexa que possa esgotar um tempo limite. Por exemplo, você precisa retornar uma resposta200
antes de atualizar uma fatura do cliente como paga no sistema de contabilidade.
Observação
Como alternativa, você pode criar um endpoint de webhook em sua linguagem de programação usando o nosso criador interativo de endpoints de webhook.
Exemplo de endpoint
Este snippet de código é uma função de webhook configurada para verificar se o tipo de evento foi recebido, gerenciar o evento e retornar uma resposta 200.
Teste seu gerenciador
Antes de implementar a função de endpoint de webhook no modo de produção, recomendamos testar a integração do aplicativo. Você pode fazer isso configurando um ouvinte local para enviar eventos à máquina local e enviando eventos de teste. Para testar, você precisa usar a CLI.
Encaminhar eventos para um endpoint local
Para encaminhar eventos ao endpoint local, execute o seguinte comando na CLI para configurar um ouvinte local. O sinalizador --forward-to
envia todos os eventos da Stripe no modo de teste para o endpoint do webhook local.
stripe listen --forward-to localhost:4242/stripe_webhooks
Observação
Você também pode executar o comando stripe listen no Stripe Shell para ver eventos no terminal do shell da Stripe , embora não seja possível encaminhar eventos do shell para o endpoint local.
Estas são algumas configurações úteis para ajudar a testar com o ouvinte local:
- Para desativar a verificação de certificados HTTPS, use o sinalizador opcional
--skip-verify
. - Para encaminhar apenas eventos específicos, use o sinalizador opcional
--events
e passe uma lista de eventos separados por vírgulas.
stripe listen --events payment_intent.created,customer.created,payment_intent.succeeded,checkout.session.completed,payment_intent.payment_failed \ --forward-to localhost:4242/webhook
- Para encaminhar eventos do endpoint de webhook público que você já registrou na Stripe para o endpoint de webhook local, use o sinalizador opcional
--load-from-webhooks-api
. Ele carrega o endpoint registrado, analisa o caminho e os eventos registrados e depois anexa o caminho ao endpoint de webhook local no--forward-to path
.
stripe listen --load-from-webhooks-api --forward-to localhost:5000
- Para verificar assinaturas de webhook, use o
{{WEBHOOK_SIGNING_SECRET}}
da saída inicial do comando escutar.
Ready! Your webhook signing secret is '{{WEBHOOK_SIGNING_SECRET}}' (^C to quit)
Acionar eventos de teste
Para enviar eventos de teste, acione um tipo de evento no qual seu destino do eventos seja assinante ao criar manualmente um objeto no Stripe Dashboard. Você também pode usar o seguinte comando no Stripe Shel ou no Stripe CLI.
Este exemplo aciona um evento payment_intent.succeeded
:
stripe trigger payment_intent.succeeded Running fixture for: payment_intent Trigger succeeded! Check dashboard for event details.
Observação
Saiba como acionar eventos com o Stripe para VS Code.
Registrar seu endpoint na Stripe
Após testar a função do endpoint do webhook, registre o URL acessível do endpoint do webhook usando a seção de webhooks no Dashboard para desenvolvedores ou a API para que a Stripe saiba onde entregar os eventos. Você pode registrar até 16 endpoints de webhook com a Stripe. Endpoints de webhook registrados precisam ser URLs de HTTPS com acesso público.
Formato do URL de webhook
O formato de URL para registrar um endpoint de webhook é:
https://<your-website>/<your-webhook-endpoint>
Por exemplo, se o seu domínio é https://mycompanysite.com
e a rota para o endpoint do webhook é @app.route('/stripe_webhooks', methods=['POST'])
, especifique o URL do endpoint como https://mycompanysite.com/stripe_webhooks
.
Adicionar um endpoint de webhook
Observação
Se você habilitou o Workbench na sua conta, é preciso usar o Workbench para registrar seu endpoint de webhook.
A Stripe aceita dois tipos de endpoints, Account e Connect. Crie um endpoint para Account, a menos que tenha criado um aplicativo Connect. Use as instruções a seguir para registrar um endpoint de webhook no Dashboard de desenvolvedores. Você pode registrar até 16 endpoints de webhook em cada conta Stripe.
- Navegue para a página Webhooks.
- Clique em Adicionar endpoint.
- Adicione o URL HTTPS do endpoint de webhook em URL do endpoint.
- Se tiver uma conta do Stripe Connect, informe uma descrição e clique Escutar eventos em contas conectadas.
- Selecione os tipos de evento que você recebe no endpoint de webhook local em Selecionar eventos.
- Clique em Adicionar endpoint.
Registrar um endpoint de webhook com a API Stripe
Você também pode criar endpoints de webhook de forma programática.
Para receber eventos de contas conectadas, use o parâmetro connect.
O exemplo a seguir cria um endpoint que notifica você quando as cobranças são bem-sucedidas ou falham.
Proteja seu endpoint
Recomendamos enfaticamente que você proteja sua integração, garantindo que o gerenciador verifique se todas as solicitações de webhook são geradas pela Stripe. Você pode optar por verificar assinaturas de webhook usando nossas bibliotecas oficiais ou verificando-as manualmente.
Depurar integrações de webhook
Vários tipos de problemas podem ocorrer na entrega de eventos ao endpoint de webhook:
- A Stripe pode não conseguir entregar um evento ao endpoint de webhook.
- O endpoint de webhook pode ter um problema de SSL.
- A conectividade de rede é intermitente.
- O endpoint de webhook não está recebendo os eventos que você espera receber.
Ver entregas de eventos
Observação
Se você habilitou o Workbench na sua conta, é preciso usar o Workbench para gerenciar suas entregas de evento.
Para ver as entregas de evento de um endpoint específico, selecione o endpoint do webhook na guia Webhooks.
Para ver todos os eventos que foram acionados na sua conta, consulte a guia Eventos.
Corrigir códigos de status HTTP
Quando um evento exibe um código de status 200
, isso indica uma entrega bem-sucedida ao endpoint do webhook. Você também pode receber um código de status diferente de 200
. Veja na tabela abaixo uma lista de códigos de status HTTP comuns e as soluções recomendadas.
Status do webhook pendente | Descrição | Correção |
---|---|---|
ERRO (Não foi possível conectar) | Não conseguimos estabelecer uma conexão com o servidor de destino. | Verifique se o domínio do host pode ser acessado pelo público da internet. |
ERRO (302 ) (ou outro status 3xx ) | O servidor de destino tentou redirecionar a solicitação para outro local. Consideramos as respostas de redirecionamento a solicitações de webhook como falhas. | Defina o destino do endpoint do webhook como o URL resolvido pelo redirecionamento. |
ERRO (400 ) (ou outro status 4xx ) | O servidor de destino não pode ou não quer processar a solicitação. Isso pode ocorrer quando o servidor detecta um erro (400 ), o URL de destino tem restrições de acesso (401 , 403 ) ou o URL de destino não existe (404 ). |
|
ERRO (500 ) (ou outro status 5xx ) | O servidor de destino encontrou um erro ao processar a solicitação. | Revise os logs do aplicativo para entender por que ele está retornando um erro 500 . |
ERRO (Erro de TLS) | Não foi possível estabelecer uma conexão segura com o servidor de destino. Estes erros geralmente são causados por um problema com o certificado SSL/ TLS ou um certificado intermediário na cadeia de certificados do servidor de destino. | Execute um teste de servidor SSL para encontrar problemas que possam causar esse erro. |
ERRO (Tempo esgotado) | O servidor de destino demorou muito para responder à solicitação do webhook. | Verifique se o código de tratamento do webhook adia o processamento de lógica complexa e retorna imediatamente uma resposta bem-sucedida. |
Comportamentos de entrega de eventos
Esta seção ajuda a entender os diferentes comportamentos esperados em relação ao modo como a Stripe envia eventos ao endpoint de webhook.
Comportamento de novas tentativas
No modo de produção, a Stripe tenta entregar um determinado evento ao endpoint de webhook por até 3 dias com um recuo exponencial. Na seção Eventos do Dashboard, você pode ver quando ocorrerá a próxima tentativa.
No modo de teste, a Stripe faz três tentativas em algumas horas. Você pode tentar transmitir novamente eventos individuais para o endpoint do webhook após esse período na seção Eventos do Dashboard. Você também pode consultar eventos perdidos para reconciliar os dados em qualquer período.
As novas tentativas automáticas continuam, mesmo se você tentar transmitir eventos de webhook individuais manualmente e a tentativa for bem-sucedida.
Se o seu endpoint tiver sido desabilitado ou excluído quando a Stripe fizer uma nova tentativa, tentativas futuras desse evento serão evitadas. No entanto, se você desabilitar e reabilitar um endpoint de webhook antes que a Stripe tente novamente, poderá ver novas tentativas.
Desativar comportamento
Nos modos de produção e teste, a Stripe tenta notificar você por e-mail sobre um endpoint configurado incorretamente se o endpoint não responder com um código de status HTTP 2xx
por vários dias seguidos. O e-mail também indica quando o endpoint será desabilitado automaticamente.
Controle de versões da API
A versão da API nas configurações da sua conta quando o evento ocorre determina a versão da API e, portanto, a estrutura de um objeto Event
enviado em um webhook. Por exemplo, se sua conta estiver definida para uma versão de API mais antiga, como 2015-02-16, e você alterar a versão da API de uma solicitação específica com controle de versão, o objeto Event
gerado e enviado ao seu endpoint ainda estará baseado na versão 2015-02-16 da API.
Não é possível alterar objetos Event
após a criação. Por exemplo, se você atualizar uma cobrança, o evento de cobrança original permanece inalterado. Isso significa que atualizações subsequentes da versão da API da sua conta não alteram retroativamente objetos Event
. A captura de eventos mais antigos chamando /v1/events
com uma versão de API mais recente também não afeta a estrutura dos eventos recebidos.
Você pode definir endpoints de webhooks de teste para a versão padrão da sua API ou a versão mais recente da API. O Event
enviado para o URL do webhook é estruturado para a versão especificada do endpoint. Você também pode programar a criação de endpoints com uma api_version específica.
Ordem de eventos
A Stripe não garante a entrega dos eventos na ordem em que foram gerados. Por exemplo, a criação de uma assinatura pode gerar os seguintes eventos:
customer.subscription.created
invoice.created
invoice.paid
charge.created
(se houver cobrança)
Seu endpoint não deve esperar a entrega desses eventos nesta ordem e deve processá-la de acordo. Você também pode usar a API para recuperar objetos ausentes (por exemplo, você pode obter os objetos de fatura, cobrança e assinatura usando as informações de invoice.paid
se receber esse evento primeiro).
Práticas recomendadas para uso de webhooks
Revise essas práticas recomendadas para garantir que seus webhooks permaneçam seguros e funcionem bem com sua integração.
Gerenciar eventos duplicados
Ocasionalmente, endpoints de webhook podem receber o mesmo evento mais de uma vez. Você pode proteger-se contra eventos duplicados tornando o processamento de eventos idempotente. Uma maneira de fazer isso é registrar os eventos que você processou e depois não processar eventos já registrados.
Ouça apenas os tipos de eventos exigidos pela sua integração
Configure seus endpoints de webhook para receber somente os tipos de eventos exigidos por sua integração. Escutar eventos adicionais (ou todos os eventos) sobrecarrega seu servidor e não é recomendável.
Você pode alterar os eventos que um endpoint de webhook recebe no Dashboard ou com a API.
Gerencie eventos de forma assíncrona
Configure o gerenciador para processar eventos recebidos com uma fila assíncrona. Você pode encontrar problemas de escalabilidade se optar por processar eventos síncronos. Qualquer pico grande em entregas de webhook (por exemplo, durante o início do mês, quando todas as assinaturas são renovadas) pode sobrecarregar os hosts do endpoint.
As filas assíncronas permitem processar os eventos simultâneos em uma taxa aceita pelo sistema.
Rota de webhook isenta de proteção contra CSRF
Se estiver usando Rails, Django ou outra estrutura da web, seu site pode verificar automaticamente se cada solicitação POST contém um token CSRF. Esse é um importante recurso de segurança que ajuda a proteger você e seus usuários contra tentativas de falsificação de solicitações entre sites. No entanto, essa medida de segurança também pode evitar que seu site processe eventos legítimos. Se for o caso, você pode precisar isentar a rota dos webhooks da proteção contra CSRF.
Receber eventos com um servidor HTTPS
Quando você usa um URL com HTTPS para o endpoint do webhook, a Stripe valida a segurança da conexão com o servidor antes de enviar dados de webhook. Para que isso funcione, o seu servidor precisa estar configurado corretamente para aceitar HTTPS com um certificado de servidor válido. O modo de produção exige URLs com HTTPS. No momento, os webhooks da Stripe não aceitam TLS v1.3.
Substituir periodicamente segredos de assinatura de endpoints
O segredo usado para verificar se os eventos chegam da Stripe é modificável na seção Webhooks do Dashboard. Para cada endpoint, clique em Substituir segredo. Você pode optar pela expiração imediata do segredo atual ou atrasar a expiração para até 24 horas para ter tempo de atualizar o código de verificação no seu servidor. Durante esse período, várias chaves secretas ficam ativas para o endpoint. A Stripe gera uma assinatura por segredo até a expiração. Para mantê-los seguros, recomendamos que você substitua os segredos periodicamente ou quando suspeitar que um deles foi comprometido.
Verificar se eventos são enviados da Stripe
A Stripe envia eventos de webhook de uma lista de endereços IP. Confie somente em eventos recebidos desses endereços IP.
Além disso, verifique as assinaturas do webhook para confirmar que os eventos recebidos foram enviados da Stripe. A Stripe assina os eventos de webhook que envia aos endpoints inserindo uma assinatura em cada cabeçalho Stripe-Signature
do evento, garantindo assim que os eventos foram enviados pela Stripe. Você pode verificar assinaturas usando as bibliotecas oficiais ou manualmente com a sua própria solução.
A seção a seguir descreve como verificar assinaturas de webhook:
- Recupere o segredo do endpoint.
- Verifique a assinatura.
Recuperar o segredo do endpoint
Use a seção Webhooks do Dashboard. Selecione um endpoint para o qual você deseja obter o segredo e encontre o segredo no canto superior direito da página.
A Stripe gera uma chave secreta única para cada endpoint. Se você usar o mesmo endpoint para chaves de API do modo de teste e do modo de produção, os segredos são diferentes uns dos outros. Além disso, se usar vários endpoints, você precisa obter um segredo para cada endpoint em que deseja verificar assinaturas e a Stripe começa a assinar cada webhook que envia ao endpoint.
Evitar ataques de repetição
Um ataque de repetição ocorre quando um invasor intercepta e retransmite um conteúdo válido e sua assinatura. Para mitigar esses ataques, a Stripe inclui um carimbo de data e hora no cabeçalho Stripe-Signature
. Como esse carimbo de data e hora faz parte do conteúdo assinado, ele também é verificado pela assinatura, de forma que um invasor não pode alterar o carimbo de data e hora sem invalidar a assinatura. Se a assinatura for válida, mas o carimbo de data e hora for muito antigo, seu aplicativo pode recusar o conteúdo.
Nossas bibliotecas têm uma tolerância padrão de cinco minutos entre o carimbo de data e hora e a hora atual. Você pode alterar essa tolerância fornecendo um parâmetro adicional quando verificar assinaturas. Use o Network Time Protocol (NTP) para assegurar que o relógio do seu servidor esteja preciso e sincroniza com a hora nos servidores da Stripe.
A Stripe gera o carimbo de data e hora e a assinatura sempre que envia um evento ao seu endpoint. Se a Stripe tentar novamente um evento (por exemplo, seu endpoint respondeu anteriormente com um código de status diferente de 2xx
), serão gerados uma nova assinatura e um novo carimbo de data e hora para a nova tentativa de entrega.
Retornar rapidamente uma resposta 2xx
O endpoint precisa retornar rapidamente um código de status de êxito (2xx
) antes de qualquer lógica complexa que possa esgotar um tempo limite. Por exemplo, você precisa retornar uma resposta 200
antes de atualizar uma fatura do cliente como paga no sistema de contabilidade.