Event Stream

The signageOS Event Stream delivers real-time domain and telemetry events to your webhook endpoints as they occur on the platform.

Set up an exporter

To start receiving these events, create an exporter that subscribes to the event types you need:

• Set up in Box (UI)
• Set up via REST API

For the concepts, see Introduction to Event Stream Distributor.

Webhook Delivery Format

Each event is delivered as an HTTP POST with a JSON body. The shape of that body is selected per exporter by its format version - see Format versions below.

Format version 1 example:

{
  "id": "0197f2a4-3a5e-7b1c-9d2f-8c4e6a1b3d5f",
  "kind": "domain",
  "type": "Device.Connect.DeviceConnected",
  "payload": { ... }
}

Format version 2 example:

Version 2 has two more fields: dispatchedAt and attemptNumber:

{
  "id": "0197f2a4-3a5e-7b1c-9d2f-8c4e6a1b3d5f",
  "kind": "domain",
  "type": "Device.Connect.DeviceConnected",
  "payload": { ... }
  "dispatchedAt": "2026-01-01T00:00:00.000Z",
  "attemptNumber": 0,
}

Field	Version	Type	Description
id	1+	string	Unique identifier of the event. It stays the same across repeated deliveries of the same event - use it to deduplicate redeliveries.
kind	1+	"domain" | "telemetry"	Category of the event
type	1+	string	Fully-qualified event type identifier
payload	1+	object	Event-specific data (see individual event pages)
dispatchedAt	2+	string	ISO 8601 timestamp of when the event happened on the platform. It stays the same across repeated deliveries of the same event and is the ordering key: deliveries can arrive out of order, so buffer them for a short window and re-sort them by dispatchedAt — never order by arrival or by X-SOS-Timestamp.
attemptNumber	2+	number	Delivery attempt starting at 0

Format versions

Every exporter carries a formatVersion (1 or 2) selecting the delivery envelope it receives. It can be set when creating the exporter and changed at any time; an exporter created without the field — including every exporter created before format versions existed — uses version 1.

A format version covers the envelope fields and header semantics only. The event-specific payload contents are not versioned — new payload fields may appear within a version at any time, so parse the payload leniently.

• Version 1 (legacy) — the four-field envelope above.
• Version 2 — adds dispatchedAt and attemptNumber. Deliveries can arrive out of order (each delivery is an independent HTTP request), so buffer them for a short window and apply them in dispatchedAt order

Webhook Headers

Every delivery includes the following HTTP headers:

Header	Description	Presence
X-SOS-Sequence-Number	Stringified integer — monotonically increasing delivery sequence	Domain events only
X-SOS-Exporter-Config-Uid	UID of the exporter configuration that produced this delivery	All events
X-SOS-Timestamp	Unix timestamp in seconds of the delivery attempt. A retried delivery is signed with a fresh value. Never use it to order or deduplicate events - use the body id to deduplicate	All events
X-SOS-Signature	Base64 HMAC-SHA256, prefixed with v1=, over {METHOD}{url}{timestamp}{body} (uppercased HTTP method, concatenated, no separators) using your configured webhook secret	All events

Event Catalogue

Alert

4 event types

Device

2 event types

Device / Provisioning Recipe

4 event types

Device / System Log

12 event types

Device / Telemetry

1 event type

Device / Verification

2 event types