Tiempo Real y Webhooks

T-Suite envía actualizaciones en vivo — nuevas notificaciones, decisiones de whitelist de wallets, aprobaciones de KYC y KYB y similares — a los usuarios con sesión iniciada mediante un stream Server-Sent Events (SSE). Esta página explica cómo se abre y se mantiene el stream, y qué existe hoy en materia de webhooks.

Cómo funciona el stream

• El stream es una respuesta text/event-stream de larga duración de la API del marketplace, una por cada pestaña abierta del navegador.
• Cada evento va dirigido a un único usuario; un usuario solo recibe sus propios eventos.
• Los eventos se originan en los servicios backend y llegan al stream a través de Kafka, de modo que un evento generado por cualquier servicio puede entregarse en vivo.
• El stream es una señal para refrescar, no la fuente de verdad. Ante un evento, el cliente vuelve a leer los datos correspondientes (contador de no leídas, listas, el registro afectado) mediante la API normal.

Paso 1 — obtener un ticket de stream de un solo uso

El EventSource del navegador no puede enviar una cabecera Authorization, y poner un token de acceso en una URL lo filtraría a logs y trazas. Por eso el stream se abre con un ticket de un solo uso:

1. Se hace un POST autenticado a /auth/notifications/stream-ticket (bajo la ruta base /marketplace/v1) con el token de acceso del usuario en la cabecera Authorization.
2. La respuesta contiene un ticket y su vida útil en segundos.

Los tickets son:

• De un solo uso — el ticket se consume al abrir el stream, aunque dos peticiones compitan por él.
• De corta duración — un ticket caduca 60 segundos después de emitirse. Conviene solicitarlo justo antes de conectar.
• Vinculados a la sesión — al canjearlo, la plataforma comprueba que la sesión que pidió el ticket siga siendo la sesión activa de la cuenta. Si el usuario cerró sesión o inició sesión en otro lugar, el ticket se rechaza.

Paso 2 — abrir el stream

Se abre un EventSource sobre /auth/notifications/stream, pasando el ticket como parámetro de consulta ticket. El token de acceso nunca aparece en la URL.

Si todo va bien, el servidor envía:

Trama	Significado
Evento hello	Se envía una vez al abrirse el stream — la conexión está activa
Eventos con nombre	Uno por actualización — por ejemplo notification, además de eventos para solicitudes y decisiones de whitelist de wallets, aprobaciones de whitelist de inversionistas, aprobaciones de KYC y KYB, y ofertas recién creadas. Cada uno lleva un contenido JSON
Comentario de heartbeat	Se envía aproximadamente cada 25 segundos para que los proxies no cierren una conexión inactiva. Los clientes lo ignoran

El conjunto de nombres de eventos puede crecer a medida que los productos añaden actualizaciones en vivo. Los nombres desconocidos deben gestionarse con tolerancia — refrescar las notificaciones es una opción segura por defecto.

Paso 3 — reconectar correctamente

Como cada ticket funciona una sola vez, es el cliente — y no la reconexión automática integrada de EventSource — quien debe encargarse de reconectar:

1. Ante un error, cerrar el EventSource.
2. Decidir si reintentar.
   • Si el stream nunca llegó a abrirse y la conexión está cerrada, o si la propia petición del ticket devolvió 401 o 403, la sesión ya no es válida. Hay que detenerse. Solo se reconecta cuando el usuario vuelva a iniciar sesión.
   • En cualquier otro caso (caída de red, reinicio del servidor, 5xx), se reintenta.
3. Aplicar backoff exponencial — la app de Libertum empieza en 2 segundos y duplica la espera hasta un máximo de 30 segundos, y la reinicia cuando una conexión se abre.
4. Obtener un ticket nuevo en cada intento. Un ticket nunca se reutiliza.

Mientras el stream esté caído, se recurre a consultar periódicamente la API de notificaciones, y esas consultas se vuelven a espaciar cuando el stream esté sano.

Webhooks

Estado: Próximamente

• Todavía no hay webhooks salientes para clientes. T-Suite no llama hoy a una URL registrada por un emisor o un socio cuando ocurre algo en la plataforma. Para reaccionar a eventos hoy, se pueden usar las notificaciones en la app, las notificaciones por correo o — para usuarios con sesión iniciada — el stream SSE descrito arriba.
• Los webhooks entrantes de proveedores son internos. La plataforma recibe llamadas de sus propios proveedores — por ejemplo SumSub (resultados de verificación de identidad), Stripe (pagos y suscripciones) y Bridge.xyz (T-Pay). Cada una se comprueba antes de procesarse — las de SumSub y Stripe, por firma. Estos endpoints existen solo para esos proveedores y no son una superficie de integración para clientes.

Si una integración necesita entrega de eventos del lado del servidor, debe plantearse a Libertum al definir el alcance de la integración.