Sistema de eventos y logging

Todo el motor de automatizaciones, webhooks y auditoría parte de un sistema de eventos unificado. Cada vez que ocurre una acción importante, los servicios de backend registran un tipo tipado y un payload estructurado. Ese registro se vuelve el punto de referencia para fans‑out, historiales y diagnósticos.

Ciclo de vida de un evento

1. Emisión: La lógica de dominio invoca el registro con un tipo y el payload ya validado.
2. Persistencia: Se inserta un registro en la tabla de eventos con id, organizationId, createdAt y el payload en JSON.
3. Fan-out automático: Se resuelven los webhooks suscritos al mismo tipo y las automatizaciones activas. Cada subsistema recibe el mismo evento serializado.
4. Observabilidad: Los resultados de webhooks quedan registrados, los hilos de automatización registran su estado y la tabla de eventos se expone en dashboards y API.
5. Encadenamiento: Las automatizaciones pueden generar nuevos eventos, permitiendo componer flujos complejos con la misma semántica.

Convenciones de evento

• Nombre: Usamos el patrón dominio:acción para evitar colisiones.
• Payload mínimo: Siempre incluye el id de la entidad principal y los ids auxiliares necesarios.
• Snapshots: Los eventos de actualización envían old y new para facilitar diffs.
• Contexto del actor: Banderas como bySystem, byAiAgent o details indican si actuó un bot, el scheduler o un usuario.

Catálogo de eventos

Para el listado completo de eventos por dominio, cuándo se disparan y los campos más relevantes del payload, consulta la página Eventos.

Agregar o extender eventos

1. Extiende la unión de tipos de eventos para que el tipo quede disponible en todo el monorepo.
2. Actualiza las constantes en las utilidades de automatizaciones para que se vean en interfaces (webhooks, automatizaciones).
3. Emite el evento desde la capa de dominio, nunca desde controladores o clientes externos.
4. Documenta el nuevo evento (por ejemplo, añade una fila en la página de Eventos y en las notas de release).

¿Necesitas construir un flujo? Comienza en Primeros pasos, configura tu webhook o automatización, y usa la página de Eventos como referencia rápida para determinar qué evento observar.