Skip to main content

Stream notifications (SSE)

GET 
/v2/config/digital-wallet/openid/notifications/sse

Streams wallet notifications for OID4VCI credential lifecycle events over Server-Sent Events. The server keeps the connection open and writes one frame for each new notification.

Authentication​

From your backend, send the Authorization header with your API key. The browser EventSource API cannot set request headers: let your backend get a one-time ticket with POST /v2/config/sse-ticket (body {"path": "/v2/config/digital-wallet/openid/notifications/sse"}), and let the browser put it in the ticket query parameter. Get a new ticket for each connection. The API key never goes in a URL.

Response headers​

Content-Type: text/event-stream, Cache-Control: no-cache.

Frames that the server writes​

  1. retry: 30000 - the server writes this frame first. It tells the client to wait 30 seconds before it reconnects.
  2. event: connected with the data {} - the server writes this frame after the subscription is live.
  3. event: notification - one frame for each new notification. The frame holds an id field and a data field with the notification object. The id is the sequence number of the notification event in the wallet: it increases and it stays the same when the server restarts, but it can hold gaps. Use it to resume the stream (see Replay).
  4. : keep-alive - an SSE comment line every 15 seconds. It carries no event, and clients ignore it.
  5. event: error - the server writes this frame when the organisation has no wallet, and it then closes the stream. The data holds one field, error. The status line is already sent at that point, so this frame arrives with HTTP 200, not with a 4xx status.

Payload of a notification frame​

The data field holds the notification object with no envelope, unlike the read and update operations, which wrap the object in notification. The object always holds these eight fields: id, organisationId, notificationType, notificationTypeRelatedId, notificationContent, status, createdAt and updatedAt. Note organisationId, which the read, update and list operations do not return. The status of a new notification is always unread, and createdAt and updatedAt are Unix timestamps in seconds.

Replay​

To get the frames that the client missed, give the id of the last frame that the client got: in the Last-Event-ID header (the EventSource API sends it itself when it reconnects), or in the lastEventId query parameter (for a client that opens a new EventSource). The server then sends the notifications after that id first, at most 500, and then the live frames. The replay can repeat a frame that the client has already. A frame for a notification id that the client has already replaces the earlier one, because the content can be new (see below). A value that is not a positive integer starts the stream without a replay.

Behaviour​

The server writes a frame when it creates a notification, and when a pending notification (for example an offer that waits for a user PIN or a deferred credential) changes to its next state: that frame has the same notification id and the new content. An update of the read status and a deletion produce no frame. When a client reads the stream too slowly, the server ends the stream of that client rather than drop frames; the client reconnects with the id of its last frame and gets the missed frames by the replay. Use the list operation to read the notifications that the wallet holds already.

This operation takes no filter parameters. The server ignores status, limit and offset on this path. Use the list operation to filter notifications.

Request​

Query Parameters

    ticket stringrequired

    One-time ticket for a client that cannot send the Authorization header, for example the browser EventSource API. Get the ticket with POST /v2/config/sse-ticket, sent with the Authorization header and the body {"path": "/v2/config/digital-wallet/openid/notifications/sse"}. The ticket is valid for 30 seconds and for one request to this path. An unknown, used or expired ticket gives 401. A request with the Authorization header needs no ticket.

    lastEventId integerrequired

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

Header Parameters

    Last-Event-ID integerrequired

    The id of the last notification frame that the client got. The EventSource API sends it itself when it reconnects. The server reads the header first and the lastEventId query parameter only without the header.

Responses​

The server opened the Server-Sent Events stream. The response stays open until the client closes the connection or the server closes the channel.

Response Headers
  • Cache-Control string

    The server always sends no-cache.

Schema

    string

Loading...
Last updated on