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 ajuda a responder a eventos assíncronos, como quando um banco confirma um pagamento, um cliente contesta uma cobrança ou um pagamento recorrente é bem-sucedido.

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

Comece já

Para começar a receber eventos de webhook no aplicativo:

1. Crie um gerenciador de endpoint de webhook para receber solicitações POST de dados de evento.
2. Teste o gerenciador de endpoint de webhook localmente usando o Stripe CLI.
3. Crie um novo destino de evento para o seu endpoint de webhook.
4. Proteja seu endpoint de 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.

Comportamentos de tipo de evento não aceitos para destinos de evento da organização

a Stripe envia a maioria dos tipos de eventos de forma assíncrona; no entanto, para determinados tipos de eventos, a Stripe aguarda uma resposta. A presença ou ausência de uma resposta do destino do evento influencia diretamente as ações da Stripe em relação a esses tipos de eventos específicos.

Os destinos da organização oferecem suporte limitado para tipos de eventos que exigem uma resposta:

• Não é possível assinar issuing_authorization.request para destinos de organização. Configure um endpoint de webhook em uma conta Stripe dentro da organização para assinar esse tipo de evento. Use issuing_authorization.request para autorizar solicitações de compra em tempo real.
• Você pode assinar checkout_sessions.completed para destinos da organização. No entanto, isso não gerencia o comportamento de redirecionamento quando você incorpora o Checkout diretamente em seu site ou redireciona os clientes para uma página de pagamento hospedada pela Stripe. A entrega de um evento checkout_sessions.completed a um destino de organização não afeta o comportamento de redirecionamento. Para influenciar o comportamento de redirecionamento do Checkout, processe esse tipo de evento com um endpoint de webhook configurado em uma conta Stripe dentro da organização.
• Você pode assinar invoice.created para destinos de organização. No entanto, a resposta malsucedida a este evento não influencia a finalização automática da fatura quando a cobrança automática é usada. Para influenciar a finalização automática da fatura por meio de respostas do endpoint do webhook, processe esse tipo de evento com um endpoint de webhook configurado em uma conta Stripe dentro da organização.

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

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

  # Extract the context
  context = event.context

  # Define your API key variables (ideally loaded securely)
  ACCOUNT_123_API_KEY = "sk_test_123"
  ACCOUNT_456_API_KEY = "sk_test_456"

  account_api_keys = {
    "account_123" => ACCOUNT_123_API_KEY,
    "account_456" => ACCOUNT_456_API_KEY
  }

  api_key = account_api_keys[context]

  if api_key.nil?
    puts "No API key found for context: #{context}"
    status 400
    return
  end

  # Handle the event
  case event.type
  when 'customer.created'
    customer = event.data.object

    begin
      latest_customer = Stripe::Customer.retrieve(
        customer.id,
        { api_key: api_key }
      )
      handle_customer_created(latest_customer, context)
    rescue => e
      puts "Error retrieving customer: #{e.message}"
      status 500
      return
    end

  when 'payment_method.attached'
    payment_method = event.data.object

    begin
      latest_payment_method = Stripe::PaymentMethod.retrieve(
        payment_method.id,
        { api_key: api_key }
      )
      handle_payment_method_attached(latest_payment_method, context)
    rescue => e
      puts "Error retrieving payment method: #{e.message}"
      status 500
      return
    end

  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.

Registrar seu endpoint

Após testar a função do endpoint do webhook, use a API ou a guia Webhooks no Workbench para registrar o URL acessível do endpoint do webhook para que Stripe saiba onde entregar os eventos. Você pode registrar até 16 endpoints de webhook com a Stripe. Os endpoints de webhook registrados precisam ser URLs HTTPS com acesso público.

Formato de 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 for https://mycompanysite.com e a rota para o endpoint do webhook for @app.route('/stripe_webhooks', methods=['POST']), especifique https://mycompanysite.com/stripe_webhooks como o URL do endpoint.

Crie um destino de evento para seu endpoint de webhook

Crie um destino de eventos usando o Workbench no Dashboard ou automaticamente com a API. Você pode registrar até 16 destinos de evento em cada conta Stripe.

Dashboard

API

Para criar um novo endpoint de webhook no Dashboard:

1. Abra a guia Webhooks no Workbench.
2. Clique em Criar um destino de evento.
3. Selecione de onde você deseja receber eventos. A Stripe aceita dois tipos de configurações: Sua conta e Contas conectadas. Selecione Conta para escutar eventos da sua própria conta. Se você criou um aplicativo Connect e quer escutar eventos das suas contas conectadas, selecione Contas conectadas.

Ouvir eventos de um endpoint de webhook da organização

Se você criar um endpoint de webhook em uma conta da organização, selecione Contas para ouvir eventos das contas da sua organização. Se você tiver plataformas Connect como membros das suas organizações e quiser ouvir eventos das contas conectadas de todas as plataformas, selecione Contas conectadas.

1. Selecione a versão da API para o objeto de eventos que você deseja consumir.
2. Selecione os tipos de evento que você deseja enviar a um endpoint de webhook.
3. Selecione Continuar e depois Endpoint do webhook como o tipo de destino.
4. Clique em Continuar e informe o URL do endpoint e uma descrição opcional do webhook.

Registrar um novo webhook usando a guia Webhooks

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.

# 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_BQokikJOvBiI2HlWgH4olfQ2'

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 webhooks

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 eventos, selecione o endpoint do webhook em Webhooks e selecione a guia Eventos.

The Events tab provides a list of events and whether they’re Delivered, Pending, or Failed. Click an event to view metadata, including the HTTP status code of the delivery attempt and the time of pending future deliveries.

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.

Novas tentativas automáticas

A Stripe tenta entregar eventos ao seu destino por até três dias com um atraso exponencial no modo de produção. Veja quando ocorrerá a próxima tentativa, se for o caso, na guia Entregas de evento do destino do evento. Fazemos novas tentativas de entrega de eventos criados em uma área restrita três vezes em poucas horas. Se seu destino tiver sido desativado ou excluído quando fizermos uma nova tentativa, impediremos futuras tentativas desse evento. No entanto, se você desativar e reativar o destino do evento antes de podermos fazer uma nova tentativa, você ainda verá novas tentativas futuras.

Novas tentativas manuais

There are two ways to manually retry events:

• In the Stripe Dashboard, click Resend when looking at a specific event. This works for up to 15 days after the event creation.
• With the Stripe CLI, run the stripe events resend <event_id> --webhook-endpoint=<endpoint_id> command. This works for up to 30 days after the event creation.

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)

Verifique se o destino de eventos não depende de receber eventos em uma ordem específica. Esteja preparado para gerenciar a entrega de forma adequada. Você também pode usar a API para recuperar objetos ausentes. Por exemplo, você pode recuperar os objetos de fatura, cobrança e assinatura com as informações de invoice.paid se receber esse evento primeiro.

Controle de versões da API

The API version in your account settings when the event occurs dictates the API version, and therefore the structure of an Event sent to your destination. For example, if your account is set to an older API version, such as 2015-02-16, and you change the API version for a specific request with versioning, the Event object generated and sent to your destination is still based on the 2015-02-16 API version. You can’t change Event objects after creation. For example, if you update a charge, the original charge event remains unchanged. As a result, subsequent updates to your account’s API version don’t retroactively alter existing Event objects. Retrieving an older Event by calling /v1/events using a newer API version also has no impact on the structure of the received event. You can set test event destinations to either your default API version or the latest API version. The Event sent to the destination is structured for the event destination’s specified version.

Práticas recomendadas para uso de webhooks

Revise essas práticas recomendadas para garantir que seus endpoints de webhook 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 o recebimento 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.

Escutar 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.

Gerenciar eventos de forma assíncrona

Configure seu gerenciador para processar eventos de entrada com uma fila assíncrona. Você pode encontrar problemas de escalabilidade se optar por processar eventos de forma síncrona. Qualquer grande pico nas entregas de webhooks (por exemplo, durante o início do mês, quando todas as assinaturas são renovadas) pode sobrecarregar seus hosts de endpoint.

As filas assíncronas permitem que você processe os eventos simultâneos em uma taxa que seu sistema possa aceitar.

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 a origem dos eventos da Stripe pode ser modificado na guia Webhooks no Workbench. Para mantê-los seguros, recomendamos que você substitua (altere) os segredos periodicamente ou quando suspeitar que um deles foi comprometido.

Para substituir um segredo:

1. Clique em cada endpoint na guia Webhooks do Workbench cujo segredo você deseja substituir.
2. Acesse o menu de navegação () e 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.

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.

Verifique também as assinaturas do webhook para confirmar que a Stripe enviou os eventos recebidos. A Stripe assina os eventos de webhook que envia aos endpoints, incluindo uma assinatura em cada cabeçalho Stripe-Signature do evento. Assim, você pode verificar se os eventos foram enviados pela Stripe e não por terceiros. Você pode verificar assinaturas usando nossas bibliotecas oficiais ou manualmente, usando 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 o Workbench e navegue até a guia Webhooks para ver todos os seus endpoints. Selecione um endpoint do qual você deseja obter o segredo e clique em Clique para revelar.

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 serã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. Após essa configuração, 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.