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 os webhooks do Connect, é importante notar que somente webhooks de teste são enviados aos URLs de webhooks de desenvolvimento, mas webhooks de produção e de teste são enviados aos URLs de webhooks de produção. Isso ocorre porque aplicativos de produção podem executar transações de produção e de teste. Por isso, recomendamos que você verifique o valor de livemode
quando recebe um evento de webhook para saber se há alguma ação a ser executada.
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":
, "livemode": true, "object": "event", "type": "customer.created", "account":"{{EVENT_ID}}", "pending_webhooks": 2, "created": 1349654313, "data": {...} }"{{CONNECTED_ACCOUNT_ID}}"
A Stripe recomenda que você ouça vários eventos relacionados a contas:
Evento | tipo data.object | Descrição |
---|---|---|
account.application.deauthorized | application | Occurs when a connected account disconnects from your platform. You can use it to trigger cleanup on your server. Available for connected accounts with access to the Stripe Dashboard, which includes Standard accounts. |
account.external_account.updated | Uma conta externa, como card ou bank_account | Ocorre quando uma conta bancária ou cartão de débito vinculado a uma conta conectada é atualizado, o que pode impactar repasses. Disponível para contas conectadas controladas pela sua plataforma, o que inclui contas Custom e Express, e contas Standard com controles de plataforma habilitados. |
account.updated | account | Permite monitorar alterações nos requisitos e mudanças de status das contas conectadas. Disponível para todas as contas conectadas. |
balance.available | balance | Occurs when your Stripe balance has been updated (for example, when funds you’ve added from your bank account are available for transfer to your connected account). |
payment_intent.succeeded | payment_intent | Occurs when a payment intent results in a successful charge. Available for all payments, including destination and direct charges. |
payout.failed | payout | Occurs when a payout fails. When a payout fails, the external account involved will be disabled, and no automatic or manual payouts can go through until the external account is updated. |
person.updated | person | Se você usa a API Persons, permite monitorar alterações nos requisitos e mudanças de status de pessoas físicas. Disponível para contas conectadas controladas pela sua plataforma, o que inclui contas Custom e Express, e contas Standard com controles de plataforma habilitados. |
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.
Se você ainda não instalou a Stripe CLI em sua máquina, instale-a agora.
Acesse sua conta Stripe e configure a CLI executando
stripe login
na linha de comando.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 estripe trigger {{EVENT_NAME}}
em outra.
Observação
Para webhooks do Connect, use --forward-connect-to
com stripe listen
e --stripe-account
com stripe trigger
.