Notifications

For detailed technical specifications, please refer to the Swagger documentation.

Notifications are intended to notify a client with all updates about their messages, including newly received messages. Notifications can be consumed using an offset-based polling or streaming approach, or via the unread notifications endpoints which return all not-yet-deleted notifications. Notifications can optionally be deleted by the client after processing.

The notification offset is global, and therefore not sequential for any user. Expect that the offset for the notifications handed to your client contain gaps!

There are several ways to receive notifications:

1. Unread polling: Fetching all unread notifications without tracking an offset using GET /notifications/unread.
2. Unread streaming: Receiving unread notifications in real-time using GET /notifications/unread/stream.
3. Offset-based polling (deprecated): Fetching notifications after a specific offset using GET /notifications.
4. Offset-based streaming (deprecated): Receiving notifications in real-time after a specific offset using GET /notifications/stream.

Note: The offset-based endpoints (3 and 4) are an alternative way to receive notifications, but are deprecated and may be discontinued in a future release. New clients should use the unread endpoints (1 and 2). A discussion of the trade-offs between the two approaches may be found in the Overall Flow documentation.

Fetch Unread Notifications (Polling, no Offset Tracking)

GET /notifications/unread
api-version: 3
nhn-source-system: YourSystemName

Returns an array of all unread notifications for one or more HER-Ids. Unlike the offset-based endpoint, this does not require tracking an offset. Notifications are considered unread until they are explicitly deleted.

Request Headers

Query Parameters

Response

The response contains an unreadNotifications array. Each notification object has the following fields:

Stream Unread Notifications (no Offset Tracking)

GET /notifications/unread/stream
api-version: 3
nhn-source-system: YourSystemName
Accept: text/event-stream

Provides a real-time stream of unread notifications using Server-Sent Events (SSE). When the connection is established, all existing unread notifications are sent first, followed by any new notifications as they arrive. Notifications should be deleted as they are handled - otherwise they will re-appear the next time the stream connects.

You should implement automatic reconnect logic, as the stream may be closed by the server (in events such as automatic replica scaling or continuous deployment).

Request Headers

Query Parameters

Stream Format

The stream sends events in the standard SSE format. Each notification is sent as a data field containing a single notification object (same structure as in the unread polling response).

Delete Notifications

POST /notifications/delete
api-version: 3
nhn-source-system: YourSystemName

Deletes one or more notifications by their IDs. This is useful when using the unread notifications endpoints, where deleted notifications are no longer returned.

Request Headers

Request Body

Response

204 No Content on success. Deleting notifications that do not exist is idempotent and will not return an error.

Fetch Notifications (Polling, with Offset Tracking) (deprecated)

GET /notifications
api-version: 3
nhn-source-system: YourSystemName

Returns an array of notifications for one or more HER-Ids. The offset you provide should be the last offset you successfully processed.

Request Headers

Query Parameters

Response

The response contains a notifications array. Each notification object has the following fields:

Stream Notifications (with Offset Tracking) (deprecated)

GET /notifications/stream
api-version: 3
nhn-source-system: YourSystemName
Accept: text/event-stream

Provides a real-time stream of notifications using Server-Sent Events (SSE).

You should implement automatic reconnect logic, as the stream may be closed by the server (in events such as automatic replica scaling or continuous deployment).

Request Headers

Query Parameters

Stream Format

The stream sends events in the standard SSE format. Each notification is sent as a data field containing a single notification object (same structure as in the polling response).

Example Stream

event: connected data:  
event: notification data: {"relatedMessageId":"0f84d750-8ce3-4471-a1ac-ab7a55e609c0","type":"MessageSentStateUpdated","notificationReceiverHerId":8139764,"notificationTriggeredByHerId":90215,"description":"Message sent to receiver.","createdAt":"2026-05-08T08:32:15.31+00:00","offset":45459}
event: notification data: {"relatedMessageId":"0f84d750-8ce3-...
event: notification data: {"relatedMessageId":"0f84d750-8ce3-...

Notification Types

NewMessage, RefusedMessage, MessageSentStateUpdated, MessageApprecInfoUpdated, MessageDeliveryStateUpdated

NewMessage

A new business document has been received and is ready for download. Use relatedMessageId to get message data from the GET /messages/{id}/*-endpoints.

RefusedMessage

A new business document has been refused and not delivered. Not available for download by the receiver.

MessageSentStateUpdated

Send-state for an outgoing business document has been updated.

MessageDeliveryStateUpdated

Transport delivery state (DeliveryState) for an outgoing business document has been updated.

MessageApprecInfoUpdated

Application receipt has been updated or received for an outgoing business document.