Webhooks do Connect

A Stripe usa webhooks para notificar os aplicativos quando um evento ocorre em sua conta. Todas as integrações do Connect devem estabelecer um endpoint de webhook para ouvir eventos do Connect.

Webhooks conectados

Uma plataforma Connect usa dois tipos de webhooks:

• Os webhooks de Account são usados para atividades da sua própria conta (por exemplo, a maioria das solicitações que usam suas chaves de API sem autenticar-se como outra conta Stripe). Incluem todos os tipos de cobrança, exceto as realizadas diretamente em uma conta conectada.
• Os webhooks do Connect são para atividades de qualquer conta conectada. Enviamos todos os eventos na conta conectada (incluindo atualizações da conta e cobranças diretas) para os webhooks do Connect.

Ao criar um webhook do Connect, você precisa configurá-lo para receber eventos de webhook do Connect. Ao criá-lo no Dashboard, em Escutar, selecione Eventos em contas conectadas. Ao criá-lo usando a API, defina o parâmetro connect como true.

Para webhooks do Connect, os URLs de webhook de desenvolvimento recebem apenas webhooks de teste, mas os URLs de webhook de produção recebem webhooks de produção e de teste. Isso ocorre porque você pode realizar transações de produção e de teste em um aplicativo de produção. Recomendamos que você verifique o valor de livemode ao receber um evento de webhook para determinar se os usuários precisam realizar uma ação.

Cada evento de conta conectada contém uma propriedade account de nível superior que identifica a conta conectada. Como a conta conectada é proprietária do objeto que acionou o evento, você precisa fazer solicitações de API para esse objeto como a conta conectada.

{
  "id": 
"{{EVENT_ID}}",
  "livemode": true,
  "object": "event",
  "type": "customer.created",
  "account": 
"{{CONNECTED_ACCOUNT_ID}}",
  "pending_webhooks": 2,
  "created": 1349654313,
  "data": {...}
}

A tabela a seguir descreve alguns dos eventos mais comuns e importantes relacionados a contas conectadas:

# Using Sinatra.
require 'sinatra'
require 'stripe'

set :port, 4242

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

# If you're 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_...'

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

  event = nil

  # Verify webhook signature and extract the event.
  # See https://stripe.com/docs/webhooks#verify-events for more information.
  begin
    event = Stripe::Webhook.construct_event(
      payload, sig_header, endpoint_secret
    )
  rescue JSON::ParserError => e
    # Invalid payload.
    status 400
    return
  rescue Stripe::SignatureVerificationError => e
    # Invalid Signature.
    status 400
    return
  end

  if event['type'] == 'account.application.deauthorized'
    application = event['data']['object']
    connected_account_id = event['account']
    handle_deauthorization(connected_account_id, application)
  end

  status 200
end

def handle_deauthorization(connected_account_id, application)
  # Clean up account state.
  puts 'Connected account ID: ' + connected_account_id
  puts application.to_s
end

Testar webhook localmente

Você pode testar webhooks localmente com a Stripe CLI.

1. Se você ainda não instalou a Stripe CLI em sua máquina, instale-a agora.

2. Acesse sua conta Stripe e configure a CLI executando stripe login na linha de comando.

3. Permita que o host local receba um evento simulado em sua conta conectada executando stripe listen --forward-to localhost:{PORT}/webhook em uma janela de terminal e stripe trigger {{EVENT_NAME}} em outra.