Manuals

English

Deutsch

English

Deutsch

Appearance

SSE Notification ​

The SSE (Server-Sent Events) notification stream is the primary mechanism for waking up a service client when new orders or commands are available. The stream sends lightweight notifications only. It never contains full order or command payloads. When a notification is received, the client should immediately poll GET /orders/location for the actual data.

Endpoint ​

text
GET https://{host}/notifications/service/stream

Headers:

HeaderRequiredDescription
api_keyYesService device API key

Query parameters:

ParameterTypeDefaultDescription
orderNumberlong-1Last processed order number for offset-based reconnect
commandNumberlong0Last processed command ID for offset-based reconnect

Response: text/event-stream (SSE stream using SseEmitter)

Event Flow ​

Once connected, the server sends events in the following sequence:

text
     Client                          Server
       |                               |
       |--- GET /notifications/service/stream --->|
       |                               |
       |<-- event: ready                 |
       |    data: {"subscriptionId": "...",|
       |           "locationName": "..."} |
       |                               |
       |<-- event: message              |  (when new orders or commands)
       |    data: {"apiKey": "...",      |
       |           "licenseCode": "...", |
       |           "scope": "..."}      |
       |                               |
       |<-- event: keepalive            |  (every 15 seconds)
       |    data: {}                   |

1. Ready Event ​

On successful connection, the server immediately sends a ready event with the subscription metadata:

text
event: ready
data: {"subscriptionId":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","locationName":"Main Floor"}

The subscriptionId uniquely identifies this SSE connection. The locationName indicates which location the client is subscribed to.

2. Message Events ​

When new orders or commands are available for the location, the server sends a message event with a MessagesAvailableEvent payload:

text
event: message
data: {"apiKey":"abc123-def456","licenseCode":"LICENSE01","scope":"SESSION"}

The MessagesAvailableEvent payload:

FieldTypeDescription
apiKeystringThe API key of the subscription.
licenseCodestringThe license code for the tenant.
scopestringEither SESSION or LICENSE, indicating the broadcast scope.

This is a signal to poll. It does not contain any order or command data.

3. Keepalive Events ​

The server sends a keepalive event every 15 seconds to keep the connection alive:

text
event: keepalive
data: {}

If no keepalive is received for 60 seconds, the client should assume the connection is dead and reconnect.

Connection Timeout ​

The service endpoint configures its emitter with a 60-minute timeout, and the scheduler sends keepalives every 15 seconds. Handle closure, timeout, and network failure by reconnecting. Do not rely on keepalives extending the stream indefinitely.

A client can use a 60-second gap without keepalives as a local reconnect threshold. This is a suggested health check, not a server guarantee about when a network failure will be reported.

Reconnection with Offset ​

When reconnecting after a disconnection, pass the last processed order number and command ID as query parameters. The offsets control which pending work triggers a notification; they are not a replay log or processing acknowledgement:

bash
curl -i -H "api_key: abc123-def456-ghi789" \
  "https://{host}/notifications/service/stream?orderNumber=12345&commandNumber=42"
  • orderNumber — The highest order number you have already processed. Pass -1 or omit for no offset (start from the beginning).
  • commandNumber — The highest command ID you have already processed. Pass 0 or omit for no offset.

The server uses these offsets to filter which orders and commands trigger notifications. It tracks the pushed offsets in memory for each subscription.

Error Responses ​

The SSE stream may return the following HTTP status codes:

StatusMeaning
401Unauthorized — Invalid or missing API key
503Service Unavailable — Server is temporarily unavailable. Client should retry with exponential backoff

Client Implementation Guidance ​

Check the stream ​

Use a service client that can send the api_key header. For a connection check:

bash
curl -N -H "api_key: abc123-def456-ghi789" \
  "https://{host}/notifications/service/stream?orderNumber=-1&commandNumber=0"

Verify that ready reports the intended location and that keepalive events follow. Trigger a controlled test operation, watch for message, then retrieve the work with Polling. The message payload contains a credential; do not copy the raw stream into logs or support tickets.

Reconnect without losing processing state ​

  1. Close the failed stream before opening another one.
  2. Use bounded exponential backoff, for example 1, 2, 4, 8 seconds, capped at 60 seconds. Stop and investigate repeated failures.
  3. Load order and command offsets from durable processing records. Keep the two identifier sequences separate.
  4. Do not advance an offset past work that still needs processing or reconciliation.
  5. Reopen the stream and poll for pending work. A ready event must not reset saved offsets.
  6. Deduplicate against durable records before repeating an external action.

Browser EventSource examples require the key in the URL. Prefer a service client with header authentication for deployed register integrations, and exclude credentials from URL and payload logging.

What the Client Must Do ​

  1. Open the SSE connection with the API key.
  2. On ready, record the subscriptionId and locationName.
  3. On message, immediately call GET /orders/location.
  4. Keep track of the last processed orderNumber and commandNumber for reconnection.
  5. If the connection drops, reconnect with exponential backoff, passing the offset parameters.

What the SSE Stream Does NOT Do ​

  • The SSE stream does not contain order data or command payloads. It is a wake-up signal only.
  • The SSE stream does not acknowledge that you have processed orders. Processing acknowledgement happens through the status update and command response endpoints.

Next Steps ​