Stream notifications (SSE)
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:
retry: 30000: first; the client waits 30 seconds before it reconnects.event: connectedwith the data{}: the subscription is live.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 notificationidand the new content. Theidof the frame is the sequence number of the notification event: it increases and survives a restart of the server, but can have gaps. Thedatais the notification object with no envelope (see the schema below).: keep-alive: a comment line after 15 seconds without a frame. Clients ignore it.event: errorwith 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
AuthorizationstringheaderrequiredYour API key with the prefix
ApiKey:ApiKey <your-api-key>. Get an API key.Scope:
notifications:read
Query parameters
ticketstringA one-time ticket from Create SSE ticket, for a client that cannot send the
Authorizationheader (a browserEventSource). It is valid for 30 seconds and one request to this path. Not needed with theAuthorizationheader.lastEvent Id integerThe
idof the lastnotificationframe that the client got, for a newEventSourcethat cannot sendLast-Event-ID. The server first sends the notifications after it (see Replay).Example:
4711
Headers
Last-Event- ID integerThe
idof the lastnotificationframe that the client got. AnEventSourcesends it when it reconnects. It takes precedence over thelastEventIdquery parameter.Example:
4711
Response
The event stream. It stays open until the client or the server closes it.
Headers
Cache-Control stringAlways
no-cache.Example:
"no-cache"
bodystringThe SSE frames: the
connected,notificationanderrorevents and the keep-alive comments. Thedataof anotificationevent is the JSON objectNotificationSseEventbelow.