Skip to main content
Notifications

Stream notifications (SSE)

GET/v4/config/ows/holder/notification-stream

Streams the new wallet notifications over Server-Sent Events (SSE): the connection stays open, and the wallet writes one frame for each new or changed notification. Use List notifications for the notifications that the wallet holds already, and to filter: this operation takes no filter.

Authentication

From a backend, send the Authorization header. A browser EventSource cannot set headers: let your backend get a one-time ticket with Create SSE ticket (body {"path": "/v4/config/ows/holder/notification-stream"}), and put it in the ticket query parameter. Get a new ticket for each connection. Never put the API key in a URL.

Frames

The answer has Content-Type: text/event-stream and Cache-Control: no-cache. The frames:

  1. retry: 30000: first; the client waits 30 seconds before it reconnects.
  2. event: connected with the data {}: the subscription is live.
  3. event: notification: one frame for each new notification, and for a pending notification (for example an offer that waits for a transaction code or a deferred credential) that changes to its next state, with the same notification id and the new content. The id of the frame is the sequence number of the notification event: it increases and survives a restart of the server, but can have gaps. The data is the notification object with no envelope (see the schema below).
  4. : keep-alive: a comment line after 15 seconds without a frame. Clients ignore it.
  5. event: error with the data {"error": "..."}: the organisation has no organisation wallet. The stream then ends. The status is already 200 at that point.

A change of the read status and a delete give no frame. When a client reads too slowly, the server ends its stream and does not drop frames: the client reconnects and gets the missed frames by the replay.

Replay

To get the frames that a client missed, give the id of the last frame that it got: in the Last-Event-ID header (an EventSource sends it when it reconnects) or in the lastEventId query parameter (for a new EventSource). The server first sends the notifications after that id (at most 500), then the live frames. A frame can come twice: keep the newest frame for each notification id, because the content can change. A value that is not a positive integer starts the stream without a replay.

Authorizations

  • Authorizationstringheaderrequired

    Your API key with the prefix ApiKey: ApiKey <your-api-key>. Get an API key.

    Scope:notifications:read

Query parameters

  • ticketstring

    A one-time ticket from Create SSE ticket, for a client that cannot send the Authorization header (a browser EventSource). It is valid for 30 seconds and one request to this path. Not needed with the Authorization header.

  • lastEventIdinteger

    The id of the last notification frame that the client got, for a new EventSource that cannot send Last-Event-ID. The server first sends the notifications after it (see Replay).

    Example:4711

Headers

  • Last-Event-IDinteger

    The id of the last notification frame that the client got. An EventSource sends it when it reconnects. It takes precedence over the lastEventId query parameter.

    Example:4711

Response

text/event-stream

The event stream. It stays open until the client or the server closes it.

Headers

  • Cache-Controlstring

    Always no-cache.

    Example:"no-cache"

  • bodystring

    The SSE frames: the connected, notification and error events and the keep-alive comments. The data of a notification event is the JSON object NotificationSseEvent below.