Events & Webhooks

Events are timestamped data points tied to the session (and the video stream, if active). The SDK automatically sends built-in events such as device health and screenshots. You can also send custom events from Unity.

Common Fields

All events share these fields:

Field	Type	Description
id	string (UUID)	Unique event identifier
sessionId	string (UUID)	The BeamXR session this event belongs to
eventType	string	Event type (e.g. StreamStarted, Health, StreamStopped, Screenshot)
timestamp	number	Unix timestamp in milliseconds

Example Events

StreamStarted - emitted when a stream begins. Contains the streamingSessionId you'll need to watch or record the stream.

{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "sessionId": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "eventType": "StreamStarted",
  "timestamp": 1709049600000,
  "streamingSessionId": "stream-9876-5432-fedc-ba0987654321"
}

Health - periodic device health snapshot.

{
  "id": "e8f9a0b1-2345-6789-abcd-ef0123456789",
  "sessionId": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "eventType": "Health",
  "timestamp": 1709049660000,
  "fps": 72,
  "cpuUsage": 45.2,
  "batteryLevel": 87
}

Querying Events

All events are returned when you fetch a session:

GET /sessions/{SessionId}

Event Types

Type	Description
Custom	User-defined events with up to 10 custom fields (custom01–custom10)
Health	Device metrics: battery, CPU, memory, FPS, error counts
Progression	Level/stage progress: start, fail, success with scores
Business	Transactions: amount, currency, item details
Resource	Resource flow: sink/source with amounts
Design	Hierarchical design events (up to 4 category levels + value)
Error	Error reports with severity: Critical, Error, Warning, Information, Debug
Impression	Ad/content impression tracking
SessionEnd	Session termination with total duration

Custom Events

Send custom events from Unity using the events ingestion endpoint. Each event requires an id, timestamp, and eventType:

{
    "events": [
        {
            "id": "unique-event-id",
            "eventType": "Custom",
            "timestamp": 100,
            "custom01": "Player completed tutorial",
            "custom02": "duration:45s"
        }
    ]
}

POST /sessions/{SessionId}/Events

Webhooks

Register a webhook to receive events in real time as they occur, rather than polling the session endpoint. Contact BeamXR to configure your webhook URL.

note

Webhook registration details and example payloads will be provided in a future update.