Receba eventos da Stripe no seu endpoint de webhook

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.

Crie um destino de evento para receber eventos em um endpoint de webhook HTTPS. Depois que você registra um endpoint de webhook, a Stripe pode enviar dados de eventos em tempo real ao endpoint do webhook do aplicativo quando os eventos ocorrerem na sua conta Stripe. A Stripe usa HTTPS para enviar eventos de webhook ao seu 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.

Você também pode receber eventos no Amazon EventBroid com destinos de evento.

Comece já

Para começar a receber eventos de webhook no aplicativo, crie e registre um endpoint de webhook:

1. Crie um gerenciador de endpoint de webhook para receber solicitações POST de dados de evento.
2. Teste o gerenciador de endpoints de webhook localmente usando a Stripe CLI.
3. Registre seu endpoint na Stripe usando o Dashboard ou a API.
4. Proteja o endpoint do webhook.

Você pode registrar e criar um endpoint para gerenciar vários tipos de eventos ao mesmo tempo ou configurar endpoints individuais para eventos específicos.

require 'json'

# Using Sinatra
post '/webhook' do
  payload = request.body.read
  event = nil

  begin
    event = Stripe::Event.construct_from(
      JSON.parse(payload, symbolize_names: true)
    )
  rescue JSON::ParserError => e
    # Invalid payload
    status 400
    return
  end

  # Handle the event
  case event.type
  when 'payment_intent.succeeded'
    payment_intent = event.data.object # contains a Stripe::PaymentIntent
    # Then define and call a method to handle the successful payment intent.
    # handle_payment_intent_succeeded(payment_intent)
  when 'payment_method.attached'
    payment_method = event.data.object # contains a Stripe::PaymentMethod
    # Then define and call a method to handle the successful attachment of a PaymentMethod.
    # handle_payment_method_attached(payment_method)
  # ... handle other event types
  else
    puts "Unhandled event type: #{event.type}"
  end

  status 200
end

stripe listen --forward-to localhost:4242/webhook

stripe listen --events payment_intent.created,customer.created,payment_intent.succeeded,checkout.session.completed,payment_intent.payment_failed \
  --forward-to localhost:4242/webhook

stripe listen --load-from-webhooks-api --forward-to localhost:4242/webhook

Ready! Your webhook signing secret is '{{WEBHOOK_SIGNING_SECRET}}' (^C to quit)

stripe trigger payment_intent.succeeded
Running fixture for: payment_intent
Trigger succeeded! Check dashboard for event details.

Registre seu endpoint

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.

Crie um endpoint de webhook

You can create new event destinations for webhook and AWS EventBridge destinations.

1. Open the Event destinations tab in Workbench.
2. Click Create new destination.
3. Select the API version for the events object you want to consume.
4. If you’re using Connect, you can listen for Events on connected accounts. Otherwise, choose Events on your account.
5. Select the event types that you want to send to the destination, then click Continue.
6. Select Webhook to send events to an HTTPS endpoint.
7. Provide the Endpoint URL for Stripe to send webhooks to and an optional description for the endpoint.
8. Click Create destination to create your webhook endpoint.

Observação

O Workbench substitui o Dashboard dos desenvolvedores existente. Se você ainda está usando o Dashboard dos desenvolvedores, veja como criar um endpoint de webhook.

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.

Command Line

curl

curl https://api.stripe.com/v1/webhook_endpoints \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "url"="https://example.com/my/webhook/endpoint" \
  -d "enabled_events[]"="payment_intent.payment_failed" \
  -d "enabled_events[]"="payment_intent.succeeded"

# Set your secret key. Remember to switch to your live secret key in production.
# See your keys here: https://dashboard.stripe.com/apikeys
Stripe.api_key = 
'sk_test_4eC39HqLyjWDarjtT1zdp7dc'

require 'stripe'
require 'sinatra'

# If you are testing your webhook locally with the Stripe CLI you
# can find the endpoint's secret by running `stripe listen`
# Otherwise, find your endpoint's secret in your webhook settings in
# the Developer Dashboard
endpoint_secret = 'whsec_...'

# Using the Sinatra framework
set :port, 4242

post '/my/webhook/url' do
  payload = request.body.read
  sig_header = request.env['HTTP_STRIPE_SIGNATURE']
  event = nil

  begin
    event = Stripe::Webhook.construct_event(
      payload, sig_header, endpoint_secret
    )
  rescue JSON::ParserError => e
    # Invalid payload
    puts "Error parsing payload: #{e.message}"
    status 400
    return
  rescue Stripe::SignatureVerificationError => e
    # Invalid signature
    puts "Error verifying webhook signature: #{e.message}"
    status 400
    return
  end

  # Handle the event
  case event.type
  when 'payment_intent.succeeded'
    payment_intent = event.data.object # contains a Stripe::PaymentIntent
    puts 'PaymentIntent was successful!'
  when 'payment_method.attached'
    payment_method = event.data.object # contains a Stripe::PaymentMethod
    puts 'PaymentMethod was attached to a Customer!'
  # ... handle other event types
  else
    puts "Unhandled event type: #{event.type}"
  end

  status 200
end

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

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.

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, os endpoints de webhook podem receber o mesmo evento mais de uma vez. Para se proteger contra recibos de eventos duplicados, registre os IDs de evento que você processou e não processe eventos já registrados.

Em alguns casos, dois objetos Event são gerados e enviados. Para identificar essas duplicatas, use o ID do objeto em data.object junto com o event.type.

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.

class StripeController < ApplicationController
  # If your controller accepts requests other than Stripe webhooks,
  # you'll probably want to use `protect_from_forgery` to add CSRF
  # protection for your application. But don't forget to exempt
  # your webhook route!
  protect_from_forgery except: :webhook

  def webhook
    # Process webhook data in `params`
  end
end

Receber eventos com um servidor HTTPS

Se você usa um URL HTTPS para seu endpoint de webhook (obrigatório no modo de produção), a Stripe valida a segurança da conexão com seu servidor antes de enviar os dados do webhook. Para que isso funcione, seu servidor precisa estar configurado corretamente para aceitar HTTPS com um certificado de servidor válido. Os webhooks da Stripe aceitam apenas as versões v1.2 e v1.3 do TLS.

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:

1. Recupere o segredo do endpoint.
2. 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.