SystemEvent

Um SystemEvent é um registro imutável de um evento de domínio. O sistema escreve um sempre que uma mudança de estado rastreada ocorre; webhooks são despachados a partir desta tabela.

Propósito

• Prover um audit log append-only de tudo que a plataforma faz.
• Direcionar a entrega de webhooks (o dispatcher poll/listen nesta tabela).
• Habilitar backfill: clientes podem listar eventos desde um timestamp em vez de depender só de push.

Schema

Campo	Tipo	Descrição
id	UUID	ID interno.
workspace_id	UUID	Workspace dono.
inbox_id	UUID | null	Inbox associada, se houver.
email_id	UUID | null	E-mail associado, se houver.
slug	string	Identificador do evento (email.db.created, etc.).
payload	object	Dados específicos do evento.
created_at / updated_at / deleted_at	datetime

Slugs atuais

Slugs de linha (workspace, inbox, agent, agent_run, webhook, email) são emitidos automaticamente em todo create/update da linha; o payload gravado aqui mantém as chaves internas em camelCase, enquanto as entregas de webhook expõem tudo em snake_case dentro de data (veja Webhook).

Slug	Emitido quando	Payload gravado
<resource>.db.created	Linha inserida	{} (+ agentId / runId / webhookId para esses recursos)
<resource>.db.updated	Linha atualizada (inclui soft delete)	{ changedFields: [...] }
email.status_changed / agent_run.status_changed	Coluna status mudou	{ status: { from, to } }
agent.version_updated	Versão do prompt incrementada	{ agentId, version: { from, to } }
email.rejected	E-mail rejeitado por política	{ reason } — um de recipient_unknown, encoding, spam, virus, recipients, filters, attachments
email.agent.processed	Agent run terminou	{ runId, totalCost, costLimitBreached, workflowRunId }
workflow.run.succeeded	Todos os passos de um workflow do agente concluíram	{ workflowRunId, runId, stepsTotal, stepsSucceeded, durationMs }
workflow.run.failed	Um workflow do agente terminou com pelo menos um passo com falha	{ workflowRunId, runId, stepsTotal, stepsSucceeded, durationMs, failedStep, failedSteps, error }
workspace.cost_limit_breached	Workspace passou do limite mensal de custo	{ runId, emailId, totalCost }
webhook.delivery.failed	Entrega esgotou as tentativas	{ webhookId, originalEventId }
webhook.ping	/webhooks/{id}/test invocado	{ webhookId, ts }

Novos slugs podem ser adicionados sem aviso. Consumidores devem ignorar slugs desconhecidos.

Exemplo

{
  "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
}

Leitura

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]. Sort padrão -created_at.

Retenção

Linhas de SystemEvent são retidas por 365 dias. Linhas mais antigas são arquivadas no S3 (Glacier) por um cron diário. Eventos arquivados não são expostos pela API.