Eventos de Brein

Todo cambio que importa en tu espacio queda anotado como un evento: llegó algo, nació un Contacto, una Oportunidad se ganó. El evento se escribe en la misma transacción que el cambio: si no se anota, el cambio tampoco ocurre. Con eso una integración o un agente puede seguir lo que pasa sin perderse nada. Lo puedes leer cuando quieras (abajo), recibirlo en tu servidor con un Destino, o suscribirte desde un agente con MCP Events.

Qué emite un evento

Emite un cambio durable en un objeto: nace, cambia de estado, se liga a otro, se llenan sus campos, o termina de procesarse algo que llegó. No emiten leer, buscar, cotizar ni proponer (el evento es lo que se hizo, no la propuesta), las comodidades de pantalla ni los reintentos que no cambiaron nada.

La forma

Cada evento es un CloudEvent 1.0:

{
  "specversion": "1.0",
  "id": "4d6f0c2e-6a1b-5f7e-9c3d-2b8a7e1f0a55",
  "source": "https://api.trybrein.com/workspaces/9a0e…",
  "type": "opportunity.moved",
  "subject": "opportunity/7b2c…",
  "time": "2026-10-15T18:04:11.000Z",
  "datacontenttype": "application/json",
  "dataschema": "https://trybrein.com/schemas/events/opportunity.moved/v0",
  "data": { "pipeline": "c1d9…", "from": "Propuesta", "to": "Ganada", "outcome": "won" },
  "workspace": "9a0e…",
  "actorkind": "human",
  "actor": "user_2f…",
  "via": "app",
  "causationid": "e81a…",
  "correlationid": "0b44…"
}

Campo	Qué es
`id`	Único. Si recibes el mismo `id` dos veces, es el mismo evento.
`type`	`objeto.verbo` en inglés. Ver el catálogo.
`subject`	`objeto/id` del objeto que cambió.
`time`	Cuándo pasó.
`dataschema`	El JSON Schema público de ese tipo.
`workspace`	Tu espacio.
`actorkind`	`human`, `agent` o `system`.
`actor`	Quién: la persona, el agente o la Fuente. Puede faltar.
`via`	Por dónde: `app`, `mcp`, `api`, `door` o `routine`.
`causationid`	El evento que causó este. Puede faltar en el primero de una cadena. Un agente que escribe de vuelta tras una entrega lo fija con el encabezado `X-Brein-Cause` (ver Destinos).
`correlationid`	El primer evento de la cadena. Con él sigues una venta hasta lo que la originó.
`runid`	La corrida de un agente, si la hubo.

data lleva referencias (ids) y qué cambió (nombres de campos, etapa anterior y nueva), nunca correo ni teléfono, y pesa hasta 20 KiB. Quien tiene permiso lee el dato completo por la API o el MCP.

Catálogo

`type`	Cuándo	`data`
`arrival.pending_decision`	La identidad es ambigua; espera a una persona.	`candidates` (número)
`arrival.failed`	Se agotaron los intentos.	`code`, `attempts`
`sequence.replied`	Un Contacto respondió a un envío de una Secuencia.	`sequence`, `contact`, `send`; opcional `opportunity`
`contact.created`	Nació un Contacto.	`origin`; opcional `company`
`contact.updated`	Cambió su correo, teléfono, LinkedIn, etapa de vida o responsable. Cualquier otro cambio no emite nada.	`fields` (nombres, nunca valores); opcional `previous` (la `lifecycle_stage` y el `owner` anteriores)
`company.created`	Nació una Empresa.	`domain`
`opportunity.created`	Nació una Oportunidad.	`pipeline`, `stage`; opcionales `company`, `contacts`
`opportunity.moved`	Cambió de etapa.	`pipeline`, `from`, `to`, `outcome` (`won`, `lost` o `null`)

El recorrido de una Llegada (recibida, decidida, aceptada, rechazada, apartada, reprocesada) no es un evento: se lee con arrival_read. El esquema exacto de cada uno, sobre incluido, está en https://trybrein.com/schemas/events/<type>/v0. Los ids son texto; un campo que no está en el esquema no se acepta.

Leer el libro

curl "https://api.trybrein.com/api/v1/workspaces/<slug>/events?limit=50" \
  -H "X-API-Key: $BREIN_API_KEY"

{ "data": [ { "specversion": "1.0", "id": "…", "type": "contact.created" } ], "next_cursor": "MTIzOjQ1", "has_more": true }

Parámetro	Qué hace
`after`	El `next_cursor` de la página anterior. Sin él, empieza desde el principio.
`types`	Tipos separados por coma: `opportunity.moved,contact.updated`.
`subject`	Un objeto exacto: `opportunity/<id>`.
`limit`	De 1 a 100. Por omisión, 50.

Para mantenerte al día, guarda next_cursor y vuelve a pedir con after. Cuando no hay nada nuevo, la respuesta trae data vacío y el mismo cursor: sigue con él. El cursor no se salta ningún evento: un evento solo aparece cuando su transacción y todas las anteriores ya terminaron, así que lo que llegue tarde siempre queda después de tu cursor. Un evento por id: GET …/workspaces/<slug>/events/<id>.

Error	Cuándo
`400` `invalid_cursor`	El cursor no es uno que Brein haya dado.
`400` `unknown_event_type`	Un tipo de `types` no está en el catálogo.
`404` `event_not_found`	Ese evento no existe en tu espacio.

Cualquier miembro del espacio puede leer su libro. Una llave de API o una app conectada lo lee con el permiso de lectura.

Inicio

Conecta

Trabaja con tu agente

Integraciones

Confianza

Para desarrolladores

Eventos de Brein

Qué emite un evento

La forma

Catálogo

Leer el libro

​Qué emite un evento

​La forma

​Catálogo

​Leer el libro

Qué emite un evento

La forma

Catálogo

Leer el libro