API specifications

APIs to enable notifications

Key Design Considerations

In order to make notifications secure, lightweight and easily deliverable and actionable, following constraints are proposed:

• Reuse existing protocol features wherever possible

• Limit the Maximum size of notification payload

• Templatized messages based on notification topic to encourage semantic interoperability

Following key APIs are envisioned to enable notifications in HCX. Full API specifications in OpenAPI 3.0 format are available here.

List supported notifications

Get the list of notification types supported by the network along with their classification and access control parameters. Key attributes of notification type master data are:

Attribute/Property	DataType	Description
title	String	The title of the notification
description	String	The details about the notification
sender	List<String>	List of roles who can send this notification.
recipient	List<String>	List of roles who can subscribe to this notification.
topic_code	String	Unique code for the notification topic
category	String	Category of the notification as detailed above - network (broadcast & target), participant, use_case
priority	int	Default priority assigned to the topic. 0 means highest, positive integer would carry the respective relative priority. Negative would be that the topic is disabled. Relative order of category for different message categories is recommended to be use_case > participant > network

API details

/notification/topic/list

As evident sanctity of the master list of notification is important for effective notification service on the network, hence it is recommended that master list of the notification is given the same treatment as an operator would give to its code for the switch.

This API is for the participants in the network to check the master list of notifications available to them.

POST/notification/list

Authorization

bearer_auth

Body

application/json

one of

ListRequest (object)

Response

200400404500

OK

Body

application/json

timestampstring

Unix timestamp when the response is sent.

Example: "1629057611000"

notificationsarray of NotificationTopic (object)

countnumber

Total number of master list notifications defined at HCX gateway with the given request filter.

Example: 1

Request

JavaScriptCurlPython

const response = await fetch('/notification/list', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer JWT",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

200400404500

{
  "timestamp": "1629057611000",
  "notifications": [
    {
      "title": "Payer Downtime",
      "description": "A notification about the Payer System Downtime. This information will be useful for all participants.",
      "sender": [
        "payor"
      ],
      "recipient": [
        "provider"
      ],
      "topic_code": "NOTIFICATION@HCX01",
      "category": "network",
      "priority": 0,
      "template": "text"
    }
  ],
  "count": 1
}

Subscription to notifications

APIs to subscribe or unsubscribe to a notification type based on its subscribability. For Use case type notifications, this API is also expected to be implemented by the participating systems supporting such notifications. Key attributes of the subscription model are:

Column	DataType	Description
subscription_id	UUID	Unique identifier for the subscription.
participant_code	String	Identifier of the subscriber.
topic_code	String	Identifier of the notification topic.
status	Integer	Status of the notification. Values: 1 - active, 0 - inactive, -1 - pending for approval.
subscription_data	Object	Encrypted details subject of subscription for the use_case category
subscribed_on	timestamp
expires_on	timestamp	Timestamp when the notification expires. Can use a reasonably long period to indicate forever valid notifications, however it is recommended that subscriptions are periodically renewed.

API details

Input would be the topic_code and payloads containing use case related details wherever applicable. The final response would be returned asynchronously.

/notification/subscribe

This API is for the participants in the network to check the master list of notifications available and subscribe to them.

The participant should send the below details in the request body while making a call for notification subscription.

• The notification topic_code (as topic_code) to understand the notification to which the participant want to subscribe.
• The sender_list from whom the notification will be expected by the subscriber.

The response to this API could be one of the following:

1. A successful accepted (202) response from the HCX gateway if the strucuture of the request is valid and the validation of open attributes (protocol headers) is successful. Upon successful validation, HCX gateway forwards the same request to the intended recipient asynchronously.
2. A successful OK (200) response from the HCX gateway if the strucuture of the request is valid and the validation of open attributes (protocol headers) is successful and the recipient is HCX gateway. There is no callback expected in this case.
3. An error response if any of the validations fail.

If the request is validated and accepted by HCX gateway, based on recipient it will be processed. If it recipient is not HCX gateway, the request will be forwarded to recipient and the participant should expect a response via callback API from recipient.

POST/notification/subscribe

Authorization

bearer_auth

Body

application/json

one of

NotificationSubscription (object)

Response

200400404500

OK

Body

application/json

timestamp*string

Unix timestamp when the response is sent.

Example: "1629057611000"

subscription_idstring

Unique identifier of the notification subscription.

Example: "SUBSCRIPTION01@HCX01"

statusnumber

Example: 1

Request

JavaScriptCurlPython

const response = await fetch('/notification/subscribe', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer JWT",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

200400404500

{
  "timestamp": "1629057611000",
  "subscription_id": "SUBSCRIPTION01@HCX01",
  "status": 1
}

/notification/unsubscribe

This API is for the participants in the network to check the subscription list and unsubscribe to them. The participant should send the below details in the request body while making a call for notification unsubscription.

1. The protocol headers defined and used by all the other APIs to understand the sender, recipient, status etc,.
2. The notification topic_code (as x-hcx-notification_subscription.topic_code) to understand the notification to which the participant want to unsubscribe.

The response to this API could be one of the following:

1. A successful accepted (202) response from the HCX gateway if the strucuture of the request is valid and the validation of open attributes (protocol headers) is successful. Upon successful validation, HCX gateway forwards the same request to the intended recipient asynchronously.
2. A successful OK (200) response from the HCX gateway if the strucuture of the request is valid and the validation of open attributes (protocol headers) is successful and the recipient is HCX gateway. There is no callback API call expected in this case.
3. An error response if any of the validations fail.

If the request is validated and accepted by HCX gateway, based on recipient it will be processed. If it recipient is not HCX gateway, the request will be forwarded to recipient and the participant should expect a response via callback API from recipient.

POST/notification/unsubscribe

Authorization

bearer_auth

Body

application/json

one of

NotificationSubscription (object)

Response

200400404500

OK

Body

application/json

timestamp*string

Unix timestamp when the response is sent.

Example: "1629057611000"

subscription_idstring

Unique identifier of the notification subscription.

Example: "SUBSCRIPTION01@HCX01"

statusnumber

Example: 1

Request

JavaScriptCurlPython

const response = await fetch('/notification/unsubscribe', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer JWT",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

200400404500

{
  "timestamp": "1629057611000",
  "subscription_id": "SUBSCRIPTION01@HCX01",
  "status": 1
}

/notification/subscription/list

This API is for the participants to get the notification subscription list.

The participant should send the below details in the request body.

POST/notification/subscription/list

Authorization

bearer_auth

Body

application/json

one of

ListRequest (object)

Response

200400404500

OK

Body

application/json

timestampstring

Unix timestamp when the response is sent.

Example: "1629057611000"

subscriptionsarray of object

countnumber

Total number of master list notifications defined at HCX gateway with the given request filter.

Example: 1

Request

JavaScriptCurlPython

const response = await fetch('/notification/subscription/list', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer JWT",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

200400404500

{
  "timestamp": "1629057611000",
  "subscriptions": [
    {
      "subscription_id": "SUBSCRIPTION01@HCX01",
      "status": 1,
      "topic_code": "NOTIFICATION@HCX01",
      "sender_list": [
        "PAYOR01@HCX01"
      ]
    }
  ],
  "count": 1
}

Trigger notifications

APIs to trigger the actual notification that would be used by the participants (including HCX switch) to notify the intended participants. This API would be used in two modes:

1. by HCX switch on participants to deliver the final notification (of all categories)

2. By participants on HCX to trigger delivery notifications of participants and use case categories on the intended recipients.

Proposed attributes of notification header and payload:

Column	DataType	Description
notificationId	String (UUID)	Unique id assigned by the initiator to the notification
sender	String	Participant code of the notification initiator
category	String	Category of the notification as defined by the specs - network, participant or use_case
topic	String	Topic of notification as defined in the master list of notifications
recipientCodes	String[]	Participant code of the recipient(s) of the notification. Could be one or more based on the need.
recipientRoles	String[]	Participant role of the recipient(s) of the notification. Could be one or more based on the need. recipientCodes and/or recipientRoles can be used to send a notification (network or participant category) to a subset of participants defined in the notification master data for the corresponding topic.
subscriptions	String[]	Conditional mandatory: list of subscription_ids (at least one) is mandatory for use_case category notifications.
Locale	String	Placeholder if localisation needs to be supported in future
reference	String	Optional reference to the context for which the notification is meant. E.g. could be correlation_id or workflow_id for a use_case notification. Maybe another notification that was sent earlier.
initiationTime	Timestamp	Protocol suggested format timestamp of when the notification was initiated by the sender
expiry	Timestamp	Expiry of the notification - should be later than initiationTime and currentTime.
message	String	Detailed message - usually picked from the template associated with the topic.
messageData	Key: Value dictionary	Key value pairs containing data for the replaceable attributes in the message template

API details

/notification/notify: return a synchronous acknowledgement of notification being received. Please note that no callback pair is defined for notify API.

This API is for the participants to explicitly send the notification to recipients via HCX gateway. The participant should send the below details in the request body while making a call to send notification.

The notification protected headers defined and used by all the other APIs to understand the sender, recipient_type, recipients etc,.

description - work in progress.

The response to this API could be one of the following:

1. A successful ok (200) response from the HCX gateway if the strucuture of the request is valid and the validation of open attributes (protocol headers) is successful. Upon successful validation, HCX gateway forwards the same request to the intended recipient asynchronously.
2. An error response if any of the validations fail.

The HCX gateway will send the notification to all the recipients of the notification if the x-hcx-recipient_id is HCX gateway identifier.

POST/notification/notify

Authorization

bearer_auth

Body

application/json

one of

NotificationRequest (object)

Response

200400404500

OK

Body

application/json

timestamp*string

Unix timestamp when the response is sent.

Example: "1629057611000"

api_call_id*string (uuid)

That is present in the transport header of the request.

correlation_id*string (uuid)

That is present in the transport header of the request.

Request

JavaScriptCurlPython

const response = await fetch('/notification/notify', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer JWT",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "payload": "eyJlbmMiOiJBMjU2R0NNIiwKImFsZyI6IlJTQS1PQUVQIiwKIngtaGN4LXNlbmRlcl9jb2RlIjoiMS00ZGMzZTA4OC1hMzEzLTQ0YWItYWZhMS0wMjIyOTU5Y2I3NWIiLAoieC1oY3gtcmVjaXBpZW50X2NvZGUiOiIxLTkzZjkwOGJhLWI1NzktNDUzZS04YjJhLTU2MDIyYWZhZDI3NSIsCiJ4LWhjeC1yZXF1ZXN0X2lkIjoiMjZiMTA2MGMtMWU4My00NjAwLTk2MTItZWEzMWUwY2E1MDkxIiwKIngtaGN4LWNvcnJlbGF0aW9uX2lkIjoiNWU5MzRmOTAtMTExZC00ZjBiLWIwMTYtYzIyZDgyMDY3NGUxIiwKIngtaGN4LXRpbWVzdGFtcCI6IjIwMjEtMTAtMjdUMjA6MzU6NTIuNjM2KzA1MzAiLAoieC1oY3gtc3RhdHVzIjoicmVxdWVzdC5pbml0aWF0ZSIsCiJ4LWhjeC13b3JrZmxvd19pZCI6IjVlOTM0ZjkwLTExMWQtNGYwYi1iMDE2LWMyMmQ4MjA2NzRlMiIsCiJ4LWhjeC1kZWJ1Z19mbGFnIjoiSW5mbyIsCiJ4LWhjeC1lcnJvcl9kZXRhaWxzIjp7ImVycm9yLmNvZGUiOiAiYmFkLmlucHV0IiwgImVycm9yLm1lc3NhZ2UiOiAiUHJvdmlkZXIgY29kZSBub3QgZm91bmQiLCAidHJhY2UiOiAiIn0sCiJ4LWhjeC1kZWJ1Z19kZXRhaWxzIjp7ImVycm9yLmNvZGUiOiAiYmFkLmlucHV0IiwgImVycm9yLm1lc3NhZ2UiOiAiUHJvdmlkZXIgY29kZSBub3QgZm91bmQiLCJ0cmFjZSI6IiJ9LAoiandzX2hlYWRlciI6eyJ0eXAiOiJKV1QiLCAiYWxnIjoiUlMyNTYifSwKImp3ZV9oZWFkZXIiOnsiYWxnIjoiUlNBLU9BRVAiLCJlbmMiOiJBMjU2R0NNIn0KfQ==.6KB707dM9YTIgHtLvtgWQ8mKwboJW3of9locizkDTHzBC2IlrT1oOQ.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY.Mz-VPPyU4RlcuYv1IwIvzw"
    }),
});
const data = await response.json();

Response

200400404500

{
  "timestamp": "1629057611000",
  "api_call_id": "123e4567-e89b-12d3-a456-426614174000",
  "correlation_id": "123e4567-e89b-12d3-a456-426614174000"
}

Updating the notification subscriptions

APIs to track and expire the notification subscription that will be used by the notification initiating participants to stop sending notifications to the subscribed participants after the expiry trigger condition is satisfied.

There can be two type of subscription expiry conditions:

1. Event based triggers

2. Time based triggers

This API will be used by the initiating participants to revoke the subscription access of the receiving participants.

Subscription update alerts

Any change in the subscription from the sending participant would be notified to all the affected receiving participants using the proposed targeted network notification capability. This is proposed to ensure that receiving participants are not inadvertently affected by change in subscription and may trigger renewal workflows for cases when subscriptions are revoked by sending participants.

API Details

/notification/subscription/update

This API is for the participants to explicitly send the notification to recipients via HCX gateway. The participant should send the below details in the request body.

• The notification topic_code (as topic_code) to understand the notification to which the participant want to subscribe.
• The sender_list from whom the notification will be expected by the subscriber.
• The status of the subscription.

The response to this API could be one of the following:

1. A successful OK (200) response from the HCX gateway if the strucuture of the request is valid. There is no callback expected in this case.
2. An error response if any of the validations fail.

If the request is validated and accepted by HCX gateway, based on recipient it will be processed. The changes to the subscription should be notified to the subscriber(s).

POST/notification/subscription/update

Authorization

bearer_auth

Body

application/json

topic_code*string

Unique notification identifier from HCX gateway using the master list.

Example: "NOTIFICATION@HCX01"

subscriber_list*array of string

The list of subscribers to which the the subscription data will be updated.

status*number

Example: 1

Response

200400404500

OK

Body

application/json

timestamp*string

Unix timestamp when the response is sent.

Example: "1629057611000"

api_call_id*string (uuid)

That is present in the transport header of the request.

correlation_id*string (uuid)

That is present in the transport header of the request.

Request

JavaScriptCurlPython

const response = await fetch('/notification/subscription/update', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer JWT",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "topic_code": "NOTIFICATION@HCX01",
      "subscriber_list": [
        "PROVIDER@HCX01"
      ],
      "status": 1
    }),
});
const data = await response.json();

Response

200400404500

{
  "timestamp": "1629057611000",
  "api_call_id": "123e4567-e89b-12d3-a456-426614174000",
  "correlation_id": "123e4567-e89b-12d3-a456-426614174000"
}