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 are delivered in a queue-like way, using an offset. Notifications do not need to be deleted by the client, just move on to handling the next notification.
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 two ways to receive notifications:
- Polling: Fetching unread notifications using a standard
GETrequest. - Streaming: Receiving notifications in real-time using Server-Sent Events (SSE).
Fetch Notifications (Polling)
GET /notifications
api-version: 3
nhn-source-system: YourSystemName
Returns an array of notifications for one or more HER-Ids.
Request Headers
| Header | Type | Required | Description |
|---|---|---|---|
api-version |
string |
✅ | Must be set to 3. |
nhn-source-system |
string |
✅ | Name and version for the client system. |
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
HerIds |
integer[] |
✅ | One or more receiver HER-Ids to fetch notifications for. |
NotificationsToFetch |
integer |
- | Number of notifications to return. Default is 100. Must be between 1 and 1000 if provided. |
Offset |
integer |
✅ | Offset of the last notification received from this endpoint, ensures only newer notifications are returned. |
Response
The response contains a notifications array. Each notification object has the following fields:
| Field | Type | Description |
|---|---|---|
relatedMessageId |
guid |
ID of the related message. Use this ID when interacting with the message-endpoints. |
type |
string |
Type of notification. Either NewMessage, RefusedMessage, MessageSentStateUpdated or MessageApprecInfoUpdated. |
notificationReceiverHerId |
integer |
The HER-Id of the receiver this notification is for. |
notificationTriggeredByHerId |
integer |
The HER-Id of the party that triggered the notification (e.g. the sender). |
description |
string |
Human-readable description of the notification event. |
createdAt |
datetime |
Timestamp for when the notification was created. |
offset |
integer |
The offset value for this notification. Use this as the Offset parameter in subsequent requests. |
Stream Notifications
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). This is the recommended way to receive notifications for systems that require low latency.
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
| Header | Type | Required | Description |
|---|---|---|---|
api-version |
string |
✅ | Must be set to 3. |
nhn-source-system |
string |
✅ | Name and version for the client system. |
Accept |
string |
✅ | Must be set to text/event-stream. |
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
HerIds |
integer[] |
✅ | One or more receiver HER-Ids to fetch notifications for. |
Offset |
integer |
✅ | Offset of the last notification received from this endpoint, ensures only newer notifications are returned. |
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 outoing business document.