Skip to main content
Feature entitlement: eventStreams · Plan: 👑 Ultra Device Plan

Event Stream Distributor

Event Stream Distributor (ESD) delivers signageOS platform events to your HTTPS webhook or Azure Event Hubs. Events include device pairing, provisioning, alerts, telemetry, connection changes, and device system logs. You configure an exporter that delivers the event types you select to your destination, so you can react to platform activity in your own systems without polling the REST API.

Choose a destination walkthrough. Each takes you from preparation to a received event, with separate instructions for Box and the REST API:

Your destinationWalkthrough
Your HTTPS endpointSend events to an HTTPS webhook
Azure Event Hubs, including device system logsSend events to Azure Event Hubs

For existing exporters, see Manage exporters for editing, credential changes, delivery monitoring, enabling, disabling, and deletion.

How it works​

An exporter filters the platform event stream to the types you subscribe to and delivers matching events to its configured destination. A webhook receives signed HTTP POST requests and returns a 2xx status to acknowledge receipt. An Azure Event Hubs exporter sends JSON messages over AMQP.

Core concepts​

  • Exporter: a configuration owned by an organization that forwards events to one destination. It has a name, an optional description, the list of event types it is subscribed to, and an enabled flag.
  • Webhook: the HTTPS url that receives the events, plus a signing secret used to sign every delivery so you can verify it came from signageOS.
  • Azure Event Hubs: an Event Hub that receives JSON event messages, including device system logs.
  • Subscribed event types: the specific events the exporter forwards (see below). An exporter delivers only the types you select.
  • Enabled: new exporters start disabled in Box. REST creation also defaults to disabled unless you pass enabled: true. You can disable an exporter later without deleting its configuration.
  • Observability: each exporter tracks cumulative counters (delivered messages, retries, errors), the time of the last successful delivery, and a list of the most recent failures, so you can see whether delivery is healthy.

Events you can subscribe to​

Use the generated Event catalogue for the current subscription identifiers and payloads. Copy the full event type, such as Device.SystemLog.ApplicationStarted, into subscribedEventTypes when configuring an exporter through the REST API.

Event categoryHTTPS webhookAzure Event Hubs
Domain events, including pairing, provisioning, and alertsSupportedSupported
Telemetry and connection changesSupportedSupported
Device system logs, Device.SystemLog.*Not supportedSupported

Only select event types supported by the exporter's destination. The REST API reference lists the allowed values for each exporter configuration.

Delivery and retries​

Delivery behavior depends on the event category:

  • Domain events use an at-least-once delivery path with a finite retry budget. Retryable failures are attempted again until the limit is reached; non-retryable failures stop immediately.
  • Most telemetry and connection events use at-most-once delivery without retries. A configured telemetry subset, which defaults to online-status telemetry, uses at-least-once delivery. If queueing that telemetry fails, delivery falls back to at-most-once.
  • Device system logs use at-most-once delivery to Azure Event Hubs without retries.

At-least-once delivery can send the same event more than once. This applies to domain events and to the retry-enabled telemetry, so your consumer must tolerate duplicate deliveries.

Retry-enabled delivery is not an unlimited guarantee of eventual receipt. The default limit for domain events and retry-enabled telemetry is 10 total attempts (the initial attempt plus up to 9 retries), with exponential backoff starting at 5 seconds and roughly doubling, with random variation, between retries. These are deployment defaults, not guaranteed retry counts or delivery deadlines; the configured values can differ.

A non-retryable failure or exhausted retry budget stops further automatic delivery of that event to the exporter. If your receiver has not accepted it, the event is lost for that exporter. Fixing the receiver afterward does not automatically restart those stopped deliveries.

At-most-once delivery can lose events without any retry. Deliveries can arrive out of order; format version 2 includes dispatchedAt to help consumers order events. Domain events also carry a per-exporter sequence number in every format version. See the delivery formats.

When exporter changes take effect​

Changes to an exporter apply to new events after a short delay, not at the moment you save them. Events that ESD accepted for delivery before the change can still arrive, including their retries. For example, you can still receive some events after you disable an exporter or remove an event type. A changed destination URL, signing secret, Azure connection, or format version also applies to those pending deliveries: their next attempt uses the new values. Update your receiver before you change the signing secret. Deleting an exporter stops its pending deliveries after the same short delay. Enabling an exporter does not send the events that occurred while it was disabled.

Webhook delivery​

Events are delivered as signed HTTP POST requests. The delivery body, the X-SOS-* headers, and the signature are documented once in the Event catalogue; the webhook walkthrough explains how to receive a delivery and verify its signature.

Webhook response rules​

Your receiver's HTTP response determines how ESD handles the delivery:

Receiver resultESD behavior
2xx, including 200, 202, and 204Accepted successfully. ESD does not retry this delivery.
408 Request Timeout or 429 Too Many RequestsEligible for another attempt only on a retry-enabled event path and while attempts remain.
Other 4xx, including 400, 401, 403, 404, and 422Non-retryable (terminal). ESD stops this delivery immediately, even if attempts remain.
5xx, request timeout, or transport failure such as DNS, connection, or TLS failureEligible for another attempt only on a retry-enabled event path and while attempts remain.

Do not return 400 or 401 for temporary application problems: ESD will not retry the event. For temporary unavailability before accepting an event, return an appropriate server error such as 503, or 429 when rate-limiting. This does not enable retries for at-most-once events; their failed deliveries are still lost. Reject invalid authentication rather than acknowledging an untrusted request.

Return 2xx only after verifying the signature and accepting responsibility for the event, for example by storing it durably for processing. Returning 202 before saving the event still tells ESD that delivery succeeded; if your application then loses it, ESD will not resend it.

Deduplicate webhook events by the body id, which stays the same across repeated deliveries. Persist the accepted event and its ID together, and return 2xx for an already accepted ID without repeating its side effects. An acknowledgment can be lost after you accept an event, so a retry does not necessarily mean the previous attempt failed at your receiver. Do not deduplicate by the signature, timestamp, or attempt number: these can change between attempts.

Next steps​