# Events

> Timestamped moments when a room changed: listed by the API, sent on the stream and delivered by webhook, with the same ID everywhere.

## Event types

- `room.occupied, room.empty` · The room's count changed, from what Cymo observed. A device going offline never empties a room.
- `zone.entered, zone.exited` · A person crossed into or out of a zone. Carries zone\_id, zone\_type and zone\_revision.
- `bed.entered, bed.exited` · A person actually got into or out of bed. Sitting up or sitting on the edge is not a bed exit.
- `posture.changed, activity.changed` · Standing, sitting, lying; walking, sitting up, turning in bed. Carries previous and current.
- `fall.detected, fall.state_changed` · A fall, then each state after it, such as on\_floor, sitting\_up and standing.
- `sleep.started, sleep.ended, sleep.stage_updated` · A sleep session and its stages, linked by sleep\_session\_id.
- `analysis.updated` · A windowed analysis, such as a sleep report, has a new revision.
- `track.associated` · Two tracks turned out to be the same person, for example across rooms.
- `device.online, device.offline, observation.gap` · Coverage changed. Missing data is reported, never filled in.

## Facts, not rules

Events describe what Cymo measured, not what you build with it. There is no "out of bed for ten minutes" or "on the floor too long" event: your app starts its own timer from the `bed.exited` or `fall.detected` timestamp and decides when to alert. That keeps the list short and lets the same events power very different products.

## Event shape

`timestamp` is when it happened; `received_at` is when the cloud got it, which differs for backfilled data. A correction keeps the event's `id` and raises its `revision`, so deduplicate by ID and keep the highest revision.

`event`

```
{
  "object": "event",
  "id": "evt_01",
  "type": "bed.exited",
  "timestamp": "2026-10-24T23:55:30.000Z",
  "received_at": "2026-10-24T23:55:30.000Z",
  "project_id": "proj_demo",
  "room_id": "room_bedroom",
  "device_id": "dev_bedroom",
  "track_id": "trk_001",
  "person_id": "person_001",
  "confidence": 0.92,
  "data": {},
  "revision": 1
}
```

Read history with [GET /v1/events](https://docs.cymatics.tech/api/list-events), filtered by `room_id`, `person_id`, `type` and time.

## Webhooks

Every event can also be delivered to your server as a signed `POST`. The [Webhooks guide](https://docs.cymatics.tech/webhooks) covers registering a URL, retries, verifying signatures and receiving deliveries on your machine.