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 do Connect

Há alguns tipos de webhooks:

• Os webhooks de conta 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). Essas atividades incluem todos os tipos de cobrança, exceto as realizadas diretamente em uma conta conectada.
• Os webhooks do Connect são para atividades em qualquer conta conectada. Todos os eventos da conta conectada são enviados aos webhooks do Connect. Isso inclui o importante evento account.updated para qualquer conta conectada e cobranças diretas.

Quando criar um webhook, verifique se ele está configurado corretamente para receber eventos de webhook do Connect. Isso pode ser feito na API configurando o parâmetro connect como true na criação do endpoint do webhook ou no Dashboard.

Para webhooks do Connect, somente webhooks de teste são enviados para seus URLs de webhook de desenvolvimento. No entanto, webhooks de produção e teste são enviados para seus URLs de webhook de produção. Isso ocorre porque você pode realizar transações em modo de produção e de teste em um aplicativo de produção. Por isso, recomendamos que você verifique o valor de livemode ao receber ummwebhook de evento para saber qual ação os usuários devem realizar (se houver).

Conforme afirmamos na referência de objeto de evento, cada evento em uma conta conectada também contém uma propriedade account de nível superior. Ela identifica a conta para a qual o webhook é enviado e o data[object] ao qual pertence. Como esses objetos pertencem a outras contas, você precisa fazer solicitações de API como a conta conectada correspondente para acessá-los.

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

A Stripe recomenda que você ouça vários eventos relacionados a contas:

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

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

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

Recomendamos que as integrações do Connect ouçam os eventos listados acima, mas há muitos outros tipos de eventos que podem ser interessantes para você.

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.