# User status update

**Event:** `user.status.update`

## Description

A user's presence changed: check-in / check-out, or their Will Return /
Out of Roam was set, cleared, or elapsed.

**Event name:** `user.status.update`

Delivered inside the standard [event envelope](/docs/webhooks/webhooks#event-envelope);
the schema below shows the full delivery body with this event's payload
under `data`.

The event payload (`data`) is the user object. `id`, `name`, and `status`
(`checkedIn` or `checkedOut`) are always present; `email` requires the
`user:read.email` scope. When a future absence is set, `data.willReturn`
is included (`returnTime`, optional `reason`, optional `outOfRoam`).
Write absences with [`user.status.set`](/docs/api/user-status-set) /
[`.clear`](/docs/api/user-status-clear).

**Required scope:** `user:read.status` (subscribe and delivery both require this
exact scope — `user:read` alone is not enough). Add `user:read.email` to include
the user's email address in the payload.

## Webhook Payload


### Example Payload

```json
{
  "type": "user.status.update",
  "eventId": "0197f9a6-5e95-7ee5-8f6a-7b8c9d0e1f2a",
  "timestamp": "2026-07-07T18:23:45.000000Z",
  "apiVersion": "2026-07-07",
  "data": {
    "id": "709b8a57-70bc-427a-b6f0-b16ba5297f8c",
    "name": "Alex Chen",
    "imageUrl": "https://ro.am/card-images/7be550c0-6994-4b8f-9a41-48825c6fc62a",
    "email": "alex.chen@example.com",
    "isAdmin": false,
    "status": "checkedIn",
    "willReturn": {
      "returnTime": "2026-09-22T09:00:00Z",
      "reason": "On vacation",
      "outOfRoam": true
    }
  }
}
```

---

*Machine-readable API documentation.*
*Full documentation: https://developer.ro.am/docs/webhooks/user-status-update*