¿En qué se diferencian los webhooks de Stripe Connect de los de Stripe normal?

Los eventos de Connect vienen de cuentas conectadas y llevan una cabecera Stripe-Account que identifica qué cuenta disparó el evento. El mecanismo de firma es el mismo que el de Stripe normal, pero debes habilitar Events on Connected accounts en el dashboard y enrutar por la cabecera en tu handler.

¿Para qué se usa la cabecera Stripe-Account?

Identifica la cuenta conectada que disparó el evento. Tu handler debería leerla antes de procesar porque el mismo tipo de evento puede dispararse en tu plataforma o en una cuenta conectada, y la lógica de negocio difiere.

¿Cómo pruebo el webhook de deautorización en local?

Configura un endpoint de Connect con un túnel, conecta una cuenta de prueba Express o Custom, luego deautorízala desde la interfaz de prueba de Connect. El evento account.application.deauthorized llega a tu handler local — reenvíalo según necesites mientras afinas la lógica de limpieza.

Webhooks de Stripe Connect: la guía de pruebas locales

Stripe Connect es un ecosistema de webhooks distinto del Stripe normal. La matemática de la firma es la misma. Todo lo demás es diferente. Si has estado cazando por qué tu handler de Connect ignora en silencio account.application.deauthorized, este artículo es para ti.

Connect cambia qué eventos recibes

Los webhooks de Stripe normal vienen de tu cuenta de plataforma: cargos, clientes, suscripciones. Los webhooks de Connect vienen de cuentas conectadas y de eventos de ciclo de vida específicos de Connect en tu plataforma. La lista se solapa bastante pero incluye eventos que solo ves con Connect habilitado:

account.updated — estado de verificación, capacidades, requisitos
account.application.deauthorized — la cuenta conectada revocó tu acceso
capability.updated — estados de activación de payouts/transferencias
person.created, person.updated — para cuentas Custom y Express
payout.failed, payout.paid — en la cuenta conectada, no en tu plataforma

La mayoría de los equipos descubren esto después de desplegar. Las pruebas locales sacan el problema a la luz en minutos.

La cabecera Stripe-Account lo cambia todo

Cuando un evento ocurre en una cuenta conectada, Stripe adjunta una cabecera Stripe-Account con el ID de la cuenta conectada (acct_xxx). Tu handler necesita enrutar según esa cabecera, no según lo que haya dentro del payload.

const connectedAccountId = req.headers['stripe-account'];
const event = stripe.webhooks.constructEvent(
  rawBody,
  req.headers['stripe-signature'],
  endpointSecret,
);

// Now process the event in the context of connectedAccountId
await handleConnectEvent(event, connectedAccountId);

Si olvidas leer la cabecera, tu handler trata cada evento de Connect como si hubiera ocurrido en tu plataforma. Los bugs de este patrón suelen aparecer como "el payout aparece para el comerciante equivocado".

Probar Connect en local con PortPreview

La configuración es la misma que la prueba local de Stripe normal, más un paso extra:

Ejecuta tu app de plataforma localmente.
Inicia un túnel: npx portpreview 3000.
En el dashboard de Stripe, añade la URL del túnel como endpoint de webhook y marca la opción Events on Connected accounts. Ese es el toggle que cambia todo el stream de eventos.
Usa una cuenta conectada de prueba Express o Custom. El modo test de Stripe incluye un creador de cuenta falso "Jenny Rosen" que dispara eventos realistas.
Dispara eventos desde la interfaz de prueba de Connect: completar onboarding, solicitar un payout, deautorizar una cuenta.

El flujo de deautorización es el difícil

Cuando una cuenta conectada revoca el acceso de tu aplicación, Stripe dispara account.application.deauthorized exactamente una vez. Si tu handler se cae, devuelve un 5xx o no confirma el evento a tiempo, Stripe reintenta — pero la cuenta conectada ya se fue. Tus llamadas API posteriores para esa cuenta devuelven 401.

Prueba el flujo de deauth con cuidado. Usa el modo test de Connect para deautorizar la cuenta de prueba, captura el webhook, y corre tu lógica de limpieza contra el payload capturado. Reenvía hasta que el camino sea a prueba de balas.

Express vs Standard vs Custom

El tipo de cuenta cambia qué eventos de person/capability recibes. Las cuentas Express y Custom emiten eventos person.* porque tu plataforma ayuda a completar el onboarding. Las cuentas Standard manejan su propio onboarding mediante pantallas alojadas por Stripe, así que ves menos eventos. Si cambias de tipo de cuenta a mitad de proyecto — y la gente lo hace — tu handler de webhooks necesita ajuste.

Lo que haríamos en realidad

Para un marketplace real con analítica a nivel de plataforma y reporting por comerciante, construye dos caminos de handler distintos desde el día uno: uno para eventos de plataforma (sin cabecera Stripe-Account), otro para eventos de cuentas conectadas. Enruta al principio de la función. Esto evita el 90% de los bugs de "¿esto es para nosotros o para el comerciante?" más adelante.

Los webhooks de Connect comparten el esquema de firma de Stripe, así que la mecánica de verificación es idéntica a la prueba de webhooks de Stripe normal. Para fondo sobre la matemática de firma entre proveedores, mira la guía de verificación de firma. Únete a la lista de espera de PortPreview para probar Connect con captura y reenvío integrados.