Estructura común
Todos los eventos siguen este shape base:Catálogo de eventos
link.created
Dispara después de un exchange exitoso. Acaba de nacer el link.
link.refreshed
El sync (automático cada 4h o on-demand) terminó OK. Trae los accounts_count actualizados.
link.expired
3 fallos consecutivos sin validar. El user debe re-conectar (widget nuevo).
link.deleted
El cliente borró el link via DELETE /v1/links/{id}. Las cuentas y movs asociados también se borraron.
account.created
Apareció una cuenta nueva en el banco bajo un link existente. Útil cuando el user abre una cuenta vista nueva, por ejemplo.
account.removed
Una cuenta dejó de aparecer en el banco (cerrada o transferida). Queda marcada como status: removed en Rail pero no se borra — para auditoría puedes seguir viendo sus movs históricos con ?include_removed=true.
refresh_intent.created
Un refresh_intent fue encolado.
refresh_intent.requires_mfa
El banco pidió MFA. Tu app debe abrir el widget con data.requires_mfa.widget_token. Ver Manejo de MFA.
refresh_intent.succeeded
Un sync terminó OK.
recovered_from — cuándo bajar el aviso de reconexión
Cuando una conexión se rompe te avisamos con un evento (link.credentials_invalid,
link.requires_mfa, link.expired, link.revoked) y vos le mostrás al usuario
que tiene que reconectar.
recovered_from es la señal de que ya lo hizo. Viene no-null en el primer
sync exitoso después de una ruptura, y dice de qué estado salió:
credentials_invalid · mfa_required · expired · revoked.
Dispara una sola vez por recuperación: en el primer sync bueno después de la
ruptura. Los siguientes vuelven a
null, porque ya no hay nada que bajar.refresh_intent.failed
Sync on-demand falló. Ver error_code en Errores → Bancos.
Suscribirse a tipos específicos
Cuando creas un webhook endpoint, especificas qué eventos quieres:["*"]. No recomendado en producción — quedas expuesto a eventos nuevos que tu handler no espera.