SystemEvent

Un SystemEvent es un registro inmutable de un evento de dominio. El sistema escribe uno cada vez que ocurre un cambio de estado rastreado; los webhooks se despachan a partir de esta tabla.

Propósito

• Proveer un log de auditoría de solo anexado (append-only) de todo lo que hace la plataforma.
• Impulsar la entrega de webhooks (el dispatcher hace poll/listen sobre esta tabla).
• Habilitar backfill: los clientes pueden listar eventos desde un timestamp en lugar de depender solo del push.

Schema

Campo	Tipo	Descripción
id	UUID	ID interno.
workspace_id	UUID	Workspace propietario.
inbox_id	UUID | null	Inbox asociado, si lo hay.
email_id	UUID | null	Correo asociado, si lo hay.
slug	string	Identificador del evento (email.db.created, etc.).
payload	object	Datos específicos del evento.
created_at / updated_at / deleted_at	datetime

Slugs actuales

Los slugs de fila (workspace, inbox, agent, agent_run, webhook, email) se emiten automáticamente en cada create/update de la fila; el payload almacenado aquí conserva las claves internas en camelCase, mientras que las entregas de webhook exponen todo en snake_case dentro de data (ver Webhook).

Slug	Se emite cuando	Payload almacenado
<resource>.db.created	Fila insertada	{} (+ agentId / runId / webhookId para esos recursos)
<resource>.db.updated	Fila actualizada (incluye soft delete)	{ changedFields: [...] }
email.status_changed / agent_run.status_changed	Cambió la columna status	{ status: { from, to } }
agent.version_updated	Versión del prompt incrementada	{ agentId, version: { from, to } }
email.rejected	Correo rechazado por política	{ reason } — uno de recipient_unknown, encoding, spam, virus, recipients, filters, attachments
email.agent.processed	El agent run terminó	{ runId, totalCost, costLimitBreached, workflowRunId }
workflow.run.succeeded	Todos los pasos de un workflow del agente terminaron	{ workflowRunId, runId, stepsTotal, stepsSucceeded, durationMs }
workflow.run.failed	Un workflow del agente terminó con al menos un paso con fallo	{ workflowRunId, runId, stepsTotal, stepsSucceeded, durationMs, failedStep, failedSteps, error }
workspace.cost_limit_breached	El workspace superó su límite mensual de costo	{ runId, emailId, totalCost }
webhook.delivery.failed	Una entrega agotó los reintentos	{ webhookId, originalEventId }
webhook.ping	Se invocó /webhooks/{id}/test	{ webhookId, ts }

Se pueden agregar nuevos slugs sin previo aviso. Los consumidores deben ignorar los slugs desconocidos.

Ejemplo

{
  "id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
  "workspace_id": "a8b2c1d4-9e7f-4a3b-8c5d-1f2e3a4b5c6d",
  "inbox_id": "b3c4d5e6-7a89-4b0c-9d1e-2f3a4b5c6d7e",
  "email_id": "e5f6a7b8-9c0d-4e1f-2a3b-4c5d6e7f8a9b",
  "slug": "email.db.created",
  "payload": {
    "email_id": "e5f6a7b8-9c0d-4e1f-2a3b-4c5d6e7f8a9b",
    "message_id": "01HZ9X8K4N0P2Q5R7S9T1V3W5X",
    "inbox_id": "b3c4d5e6-7a89-4b0c-9d1e-2f3a4b5c6d7e"
  },
  "created_at": "2026-05-17T10:00:14.130Z",
  "updated_at": "2026-05-17T10:00:14.130Z",
  "deleted_at": null
}

Lectura

Método	Path
GET	/system-events?slug=email.agent.processed&created_at[gte]=…
GET	/system-events/{id}

Filtros: slug, inbox_id, email_id, created_at[gte|lt]. Ordenación por defecto -created_at.

Retención

Las filas de SystemEvent se retienen durante 365 días. Las filas más antiguas se archivan en S3 (Glacier) mediante un cron diario. Los eventos archivados no se exponen a través de la API.