Event Stream

The signageOS Event Stream delivers domain and telemetry events to HTTPS webhooks or Azure Event Hubs. Device system logs are available through Azure Event Hubs only. See the supported destinations and delivery guarantees before choosing event subscriptions.

Set up an exporter

Choose a destination walkthrough or manage an existing exporter:

• Send events to an HTTPS webhook (Box or REST)
• Send events to Azure Event Hubs (Box or REST)
• Manage exporters

For the concepts, see Introduction to Event Stream Distributor.

Delivery format

Both destinations receive a JSON event body. Webhooks receive it in an HTTP POST; Azure Event Hubs receives it as an AMQP message. The exporter's format version selects the envelope below.

Format version 1 example

{
  "id": "0197f2a4-3a5e-7b1c-9d2f-8c4e6a1b3d5f",
  "kind": "domain",
  "type": "Device.Verification.DevicePaired",
  "payload": {
    "deviceIdentityHash": "8d6b3da0xxxxxxxxxxxxxxxx1d40293e",
    "owner": {
      "ownershipType": "organization",
      "organizationUid": "8742ac98xxxxxxxxxxxxxxxx4b8c354c",
      "parentCompanyUid": "5e4d8e7cxxxxxxxxxxxxxxxx6dcde5ea"
    },
    "type": "Device.Verification.DevicePaired",
    "verificationHash": "1c61025fxxxxxxxxxxxxxxxxc517e042"
  }
}

Format version 2 example

Version 2 has two more fields: dispatchedAt and attemptNumber:

{
  "id": "0197f2a4-3a5e-7b1c-9d2f-8c4e6a1b3d5f",
  "kind": "domain",
  "type": "Device.Verification.DevicePaired",
  "payload": {
    "deviceIdentityHash": "8d6b3da0xxxxxxxxxxxxxxxx1d40293e",
    "owner": {
      "ownershipType": "organization",
      "organizationUid": "8742ac98xxxxxxxxxxxxxxxx4b8c354c",
      "parentCompanyUid": "5e4d8e7cxxxxxxxxxxxxxxxx6dcde5ea"
    },
    "type": "Device.Verification.DevicePaired",
    "verificationHash": "1c61025fxxxxxxxxxxxxxxxxc517e042"
  },
  "dispatchedAt": "2026-01-01T00:00:00.000Z",
  "attemptNumber": 0
}

Field	Version	Type	Description
id	1+	string	Event identifier. Stable across repeated domain and telemetry deliveries; use it to deduplicate them. System logs receive a new ID at export time, not a stable deduplication key.
kind	1+	"domain" | "telemetry" | "systemLog"	Event category. System logs are available through Azure Event Hubs only.
type	1+	string	Full subscription identifier from the catalogue below.
payload	1+	object	Event-specific data, documented on each event page.
dispatchedAt	2+	string	ISO 8601 event time. Stable across retries. Deliveries can arrive out of order; buffer and sort by this field, not arrival time or X-SOS-Timestamp.
attemptNumber	2+	number	Delivery attempt starting at 0. Increases on retries; always 0 for events delivered without retries. A duplicate delivery can repeat the same number, so do not use it to deduplicate.

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 uses version 1, including exporters created before format versions existed.

A format version covers the envelope fields and header semantics only. Event-specific payload contents are not versioned. New payload fields may appear 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, so buffer them for a short window and apply them in dispatchedAt order.

Webhook headers

Webhook deliveries include the following HTTP headers:

Header	Description	Presence
X-SOS-Sequence-Number	Stringified integer. A counter per exporter, assigned when ESD accepts the event and kept on retries. Deliveries can arrive out of order; a gap means that an event is still pending or failed	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

Azure Event Hubs metadata

Azure Event Hubs messages carry the same JSON body, with messageId set to the event ID. Metadata is sent as lowercase AMQP application properties, rather than HTTP headers:

Property	Description
x-sos-exporter-config-uid	Exporter configuration UID.
x-sos-timestamp	Delivery-attempt time as a Unix timestamp in milliseconds. Webhook timestamps use seconds.
x-sos-sequence-number	Domain events only. The same per-exporter counter as the webhook header, sent as a number.

Webhook HMAC signatures do not apply to Azure Event Hubs messages.

Event catalogue

Alert

Event type	Emitted when
Alert.AlertArchived	Emitted when a user resolves the whole alert. The alert's devices stay assigned; consumers tracking per-device alert state should treat all previously assigned devices as no longer alerting.
Alert.AlertDeviceAssigned	Emitted when an alert becomes active on a device, one event per device.
Alert.AlertDeviceUnassigned	Emitted when an alert stops being active on a device, one event per device.
Alert.AlertUnarchived	Emitted when a user reverts a manual alert resolution. The alert becomes active again with the same device assignments it had when it was resolved; no new AlertDeviceAssigned events are emitted.

Device

Event type	Emitted when
Device.DeviceConnectionAdded	Emitted when a device's socket connection goes online.
Device.DeviceConnectionDeleted	Emitted when a device's socket connection goes offline.

Device / Provisioning Recipe

Event type	Emitted when
Device.ProvisioningRecipeCreated	Emitted when a new provisioning recipe is created for a device.
Device.ProvisioningRecipeDeleted	Emitted when a provisioning recipe is deleted.
Device.ProvisioningRecipeStatusUpdated	Emitted when the status of a provisioning recipe changes (e.g. Pending, Applied, Failed).
Device.ProvisioningRecipeUpdated	Emitted when an existing provisioning recipe is updated.

Device / System Log

Event type	Emitted when
Device.SystemLog.AppletRunning	Periodic report that an applet is running on a device.
Device.SystemLog.AppletStarted	Reported when an applet starts on a device.
Device.SystemLog.ApplicationStarted	Reported when the signageOS application starts on a device.
Device.SystemLog.AutoRecoveryPerformed	Reported when a device recovered itself while the application was not running.
Device.SystemLog.DeviceAlive	Periodic keep-alive reported by a running device.
Device.SystemLog.DisplayConnectedOverSerial	Reported when a display is connected to a device over a serial line.
Device.SystemLog.NetworkChanged	Reported when a device's network interfaces change.
Device.SystemLog.PolicyChanged	Reported when the policy applied on a device changes.
Device.SystemLog.PowerActionPerformed	Reported when a power action (reboot, applet restart, display power, …) is performed on a device.
Device.SystemLog.SocketConnected	Reported when a device establishes its socket connection to the platform.
Device.SystemLog.SocketConnectionFailed	Reported when a device fails to establish its socket connection to the platform.
Device.SystemLog.SocketDisconnected	Reported when a device's socket connection to the platform is closed.
Device.SystemLog.TimeSettingsChanged	Reported when a device's time settings change.

Device / Telemetry

Event type	Emitted when
Device.Telemetry.DeviceTelemetryRecordUpdated	Emitted when a device telemetry record is updated, such as a reported volume or brightness measurement. name identifies the measurement, and data contains its corresponding value.

Device / Verification

Event type	Emitted when
Device.Verification.DevicePaired	Emitted when a device is paired with a verification hash.
Device.Verification.DeviceUnpaired	Emitted when a device is unpaired from its verification hash.