Webhooks de Connect
Stripe utiliza webhooks para notificar a tu aplicación cuando hay algún evento en tu cuenta. Todas las integraciones de Connect deben establecer un punto de conexión de webhooks para escuchar los eventos de Connect.
Webhooks de Connect
Existen varios tipos de webhooks:
- Los webhooks Account son para actividades en tu propia cuenta (por ejemplo, la mayoría de las solicitudes hechas con tus claves API cuando no te autenticas como otra cuenta de Stripe). Esto incluye todo tipo de cargos, excepto los efectuados directamente en una cuenta conectada.
- Los webhooks Connect son para actividades en cualquier cuenta conectada. Todos los eventos de la cuenta conectada se envían a los webhooks de Connect. Esto incluye el importante evento
account.updated
para cualquier cuenta conectada y cargos directos.
Al crear tu webhook, asegúrate de que esté correctamente configurado para recibir eventos de webhooks de Connect. Para ello, puedes usar la API estableciendo el parámetro connect en true
, al crear el punto de conexión de webhooks, o el Dashboard.
Respecto a los webhooks Connect, cabe señalar que si bien solo se enviarán webhooks de prueba a tus URL de webhooks de desarrollo, a las URL de webhooks de producción, se enviarán webhooks tanto activos como de prueba. Esto se debe a que en una aplicación activa, puedes efectuar transacciones tanto reales como de prueba. Por esta razón, recomendamos que verifiques el valor livemode
al recibir un webhook de evento para saber qué medida debes tomar, si fuera necesario.
Como indicamos en la referencia sobre el objeto Event, cada evento de una cuenta conectada contendrá también una propiedad account
de nivel superior. Esta propiedad identifica la cuenta a la que se envía el webhook y el data[object]
al que pertenece. Debido a que estos objetos pertenecen a otras cuentas, debes solicitar las API como la cuenta conectada correspondiente para acceder a ellos.
{ "id":
, "livemode": true, "object": "event", "type": "customer.created", "account":"{{EVENT_ID}}", "pending_webhooks": 2, "created": 1349654313, "data": {...} }"{{CONNECTED_ACCOUNT_ID}}"
Hay varios eventos relacionados con cuentas que Stripe te recomienda escuchar:
Evento | tipo data.object | Descripción |
---|---|---|
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 | Una cuenta externa, como card o bank_account | Tiene lugar cuando se actualiza una cuenta bancaria o tarjeta de débito asociada a una cuenta conectada, lo que puede influir en las transferencias a cuentas bancarias. Disponible para las cuentas conectadas que controla tu plataforma, que incluye cuentas Custom y Express, y cuentas Standard con controles de plataforma habilitados. |
account.updated | account | Te permite monitorear los cambios en los requisitos de la cuenta conectada y los cambios de estado. Disponible para todas las cuentas 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 | Si usas la API Persons, te permite monitorear los cambios en los requisitos y los cambios de estado para particulares. Disponible para las cuentas conectadas que controla tu plataforma, que incluye cuentas Custom y Express, y cuentas Standard con controles de plataforma habilitados. |
Los eventos mencionados arriba son los que recomendamos que escuchen las integraciones de Connect, pero existen muchos otros tipos de eventos que te pueden interesar.
Probar webhooks a nivel local
Puedes probar webhooks a nivel local con la CLI de Stripe.
Si aún no lo has hecho, instala la CLI de Stripe en tu equipo.
Inicia sesión en tu cuenta Stripe y configura la CLI ejecutando
stripe login
en la línea de comandos.Le permite a tu host local recibir un evento simulado en tu cuenta conectada ejecutando
stripe listen --forward-to localhost:{PORT}/webhook
en una ventana de terminal ystripe trigger {{EVENT_NAME}}
en otra.
Nota
Para webhooks de Connect, usa --forward-connect-to
con stripe listen
y --stripe-account
con stripe trigger
.