openapi: 3.0.1 info: title: HCX Notification APIs description: >- The Health Claims Exchange (HCX) is a digital infrastructure designed to enable automated, data-driven management of health insurance claims in an open ecosystem. These API specifications enable all actors to consume, subscribe or unsubscribe and send notifications in the ecosystem. license: name: Apache 2.0 url: 'http://www.apache.org/licenses/LICENSE-2.0.html' version: 0.9.0 externalDocs: description: HCX Specifications url: >- https://docs.swasth.app/hcx-specifications/ tags: - name: Notification APIs description: >- APIs for notification subscription management and send and receive the callback requests. paths: /notification/list: post: tags: - Notification APIs description: >- This API is for the participants in the network to check the master list of notifications available to them. requestBody: content: application/json: schema: oneOf: - $ref: '#/components/schemas/ListRequest' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/NotificationTopicListResponse' '400': description: Request Validation failed content: application/json: schema: $ref: '#/components/schemas/StandardErrorResponse' '404': description: Requested resource was not found content: application/json: schema: $ref: '#/components/schemas/StandardErrorResponse' '500': description: Downstream systems down/unhandled exceptions. content: application/json: schema: $ref: '#/components/schemas/StandardErrorResponse' security: - bearer_auth: [] /notification/subscribe: post: tags: - Notification APIs description: >- 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. requestBody: content: application/json: schema: required: - topic_code - sender_list oneOf: - $ref: '#/components/schemas/NotificationSubscription' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/StandardSuccessResponse' '400': description: Request Validation failed content: application/json: schema: $ref: '#/components/schemas/StandardErrorResponse' '404': description: Requested resource was not found content: application/json: schema: $ref: '#/components/schemas/StandardErrorResponse' '500': description: Downstream systems down/unhandled exceptions. content: application/json: schema: $ref: '#/components/schemas/StandardErrorResponse' security: - bearer_auth: [] /notification/unsubscribe: post: tags: - Notification APIs description: >- 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. requestBody: content: application/json: schema: required: - topic_code - sender_list oneOf: - $ref: '#/components/schemas/NotificationSubscription' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/StandardSuccessResponse' '400': description: Request Validation failed content: application/json: schema: $ref: '#/components/schemas/StandardErrorResponse' '404': description: Requested resource was not found content: application/json: schema: $ref: '#/components/schemas/StandardErrorResponse' '500': description: Downstream systems down/unhandled exceptions. content: application/json: schema: $ref: '#/components/schemas/StandardErrorResponse' security: - bearer_auth: [] /notification/subscription/list: post: tags: - Notification APIs description: >- This API is for the participants to get the notification subscription list. The participant should send the below details in the request body. requestBody: content: application/json: schema: oneOf: - $ref: '#/components/schemas/ListRequest' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/SubscriptionListResponse' '400': description: Request Validation failed content: application/json: schema: $ref: 'https://raw.githubusercontent.com/hcx-project/hcx-specs/v0.9/API%20Definitions/openapi_hcx.yaml#/components/schemas/ErrorResponse' '404': description: Requested resource was not found content: application/json: schema: $ref: 'https://raw.githubusercontent.com/hcx-project/hcx-specs/v0.9/API%20Definitions/openapi_hcx.yaml#/components/schemas/ErrorResponse' '500': description: Downstream systems down/unhandled exceptions. content: application/json: schema: $ref: 'https://raw.githubusercontent.com/hcx-project/hcx-specs/v0.9/API%20Definitions/openapi_hcx.yaml#/components/schemas/ErrorResponse' security: - bearer_auth: [] /notification/subscription/update: post: tags: - Notification APIs description: >- 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). requestBody: content: application/json: schema: required: - topic_code - subscriber_list - status properties: topic_code: type: string description: Unique notification identifier from HCX gateway using the master list. example: "NOTIFICATION@HCX01" subscriber_list: type: array description: The list of subscribers to which the the subscription data will be updated. items: type: string example: "PROVIDER@HCX01" status: type: number example: 1 responses: '200': description: OK content: application/json: schema: $ref: 'https://raw.githubusercontent.com/hcx-project/hcx-specs/v0.9/API%20Definitions/openapi_hcx.yaml#/components/schemas/SuccessResponse' '400': description: Request Validation failed content: application/json: schema: $ref: 'https://raw.githubusercontent.com/hcx-project/hcx-specs/v0.9/API%20Definitions/openapi_hcx.yaml#/components/schemas/ErrorResponse' '404': description: Requested resource was not found content: application/json: schema: $ref: 'https://raw.githubusercontent.com/hcx-project/hcx-specs/v0.9/API%20Definitions/openapi_hcx.yaml#/components/schemas/ErrorResponse' '500': description: Downstream systems down/unhandled exceptions. content: application/json: schema: $ref: 'https://raw.githubusercontent.com/hcx-project/hcx-specs/v0.9/API%20Definitions/openapi_hcx.yaml#/components/schemas/ErrorResponse' security: - bearer_auth: [] /notification/notify: post: tags: - Notification APIs description: >- 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. 3. 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. requestBody: content: application/json: schema: oneOf: - $ref: '#/components/schemas/NotificationRequest' responses: '200': description: OK content: application/json: schema: $ref: 'https://raw.githubusercontent.com/hcx-project/hcx-specs/v0.9/API%20Definitions/openapi_hcx.yaml#/components/schemas/SuccessResponse' '400': description: Request Validation failed content: application/json: schema: $ref: 'https://raw.githubusercontent.com/hcx-project/hcx-specs/v0.9/API%20Definitions/openapi_hcx.yaml#/components/schemas/ErrorResponse' '404': description: Requested resource was not found content: application/json: schema: $ref: 'https://raw.githubusercontent.com/hcx-project/hcx-specs/v0.9/API%20Definitions/openapi_hcx.yaml#/components/schemas/ErrorResponse' '500': description: Downstream systems down/unhandled exceptions. content: application/json: schema: $ref: 'https://raw.githubusercontent.com/hcx-project/hcx-specs/v0.9/API%20Definitions/openapi_hcx.yaml#/components/schemas/ErrorResponse' security: - bearer_auth: [] components: schemas: NotificationJWSPayload: required: - payload type: object format: byte description: This object is used as payload in the HCX protocol APIs that require the request body to sent in JWS format (as defined in [RFC-7515](https://datatracker.ietf.org/doc/html/rfc7515)). properties: payload: type: object format: string description: The paylod should be a JWS token containing the following elements. 1. JWS Protected headers (**protected**) - A set of attributes that provide transport, security, message integrity and summary information about the message being exchanged. 2. JWS Payload (**payload**) - Payload containing the relevant domain entity (eObject) as prescribed for the use case by the domain specifications. This needs to be encrypted so that HCX cannot read this. 3. JWS Signature (**signature**) - Digital signature on the protected header and the payload of the message to ensure its integrity. The final payload should be serialzed using JWS compact serialization as defined in the RFC-7515 - **protected || '.' || payload || '.' || signature** Detailed steps on how to construct the JWS token are provided in this [section](https://docs.swasth.app/hcx-specifications/hcx-technical-specifications/open-protocol/data-security-and-privacy/message-security-and-integrity#message-encryption) of the HCX specifications. example: "eyJlbmMiOiJBMjU2R0NNIiwKImFsZyI6IlJTQS1PQUVQIiwKIngtaGN4LXNlbmRlcl9jb2RlIjoiMS00ZGMzZTA4OC1hMzEzLTQ0YWItYWZhMS0wMjIyOTU5Y2I3NWIiLAoieC1oY3gtcmVjaXBpZW50X2NvZGUiOiIxLTkzZjkwOGJhLWI1NzktNDUzZS04YjJhLTU2MDIyYWZhZDI3NSIsCiJ4LWhjeC1yZXF1ZXN0X2lkIjoiMjZiMTA2MGMtMWU4My00NjAwLTk2MTItZWEzMWUwY2E1MDkxIiwKIngtaGN4LWNvcnJlbGF0aW9uX2lkIjoiNWU5MzRmOTAtMTExZC00ZjBiLWIwMTYtYzIyZDgyMDY3NGUxIiwKIngtaGN4LXRpbWVzdGFtcCI6IjIwMjEtMTAtMjdUMjA6MzU6NTIuNjM2KzA1MzAiLAoieC1oY3gtc3RhdHVzIjoicmVxdWVzdC5pbml0aWF0ZSIsCiJ4LWhjeC13b3JrZmxvd19pZCI6IjVlOTM0ZjkwLTExMWQtNGYwYi1iMDE2LWMyMmQ4MjA2NzRlMiIsCiJ4LWhjeC1kZWJ1Z19mbGFnIjoiSW5mbyIsCiJ4LWhjeC1lcnJvcl9kZXRhaWxzIjp7ImVycm9yLmNvZGUiOiAiYmFkLmlucHV0IiwgImVycm9yLm1lc3NhZ2UiOiAiUHJvdmlkZXIgY29kZSBub3QgZm91bmQiLCAidHJhY2UiOiAiIn0sCiJ4LWhjeC1kZWJ1Z19kZXRhaWxzIjp7ImVycm9yLmNvZGUiOiAiYmFkLmlucHV0IiwgImVycm9yLm1lc3NhZ2UiOiAiUHJvdmlkZXIgY29kZSBub3QgZm91bmQiLCJ0cmFjZSI6IiJ9LAoiandzX2hlYWRlciI6eyJ0eXAiOiJKV1QiLCAiYWxnIjoiUlMyNTYifSwKImp3ZV9oZWFkZXIiOnsiYWxnIjoiUlNBLU9BRVAiLCJlbmMiOiJBMjU2R0NNIn0KfQ==.6KB707dM9YTIgHtLvtgWQ8mKwboJW3of9locizkDTHzBC2IlrT1oOQ.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY.Mz-VPPyU4RlcuYv1IwIvzw" properties: protected: type: object format: string description: >- Protected headers contain information that helps HCX gateway to identify senders, receivers of the message, perform integrity checks, audits and routing functionality. Header values are posted in clear and must never contain any Personally Identifiable Information (PII) about the patient or any person. HCX protocol uses JWS protected headers for such information to ensure these are not tampered with by the intermediate gateways. Protected Headers for HCX will be the union of the following three header categories. JOSE Headers - JSON Web Signature header as per [RFC7515](https://datatracker.ietf.org/doc/html/rfc7515#page-9). For HCX, this is proposed to be fixed to {"alg":"RS256"}. Notification Protected Headers - The JWS protected headers as per [RFC7515](https://datatracker.ietf.org/doc/html/rfc7515#page-9). The list of header allowed for the notification request to define the recipients and the details about the notification. Overall, the protected headers should be created as - JWS Protected Header = BASE64URL(UTF8(JOSE headers) + UTF8( Notification headers)) allOf: - required: - x-hcx-notification_headers - $ref: '#/components/schemas/JOSEHeader' - properties: x-hcx-notification_headers: type: object description: TODO allOf: - $ref: '#/components/schemas/NotificationHeaders' example: "eyJlbmMiOiJBMTI4Q0JDLUhTMjU2In0" payload: type: string description: Payload contains the notification data that needs to sent to the recipient. The payload value should be Base64 encoded value of the NotificationData object - BASE64URL(NotificationData). example: "eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFtcGxlLmNvbS9pc19yb290Ijp0cnVlfQ" signature: type: string description: The JWS Signature generated by signing the concatenated value of protected header and payload (ASCII(BASE64URL(UTF8(JWS Protected Header)) || '.' || BASE64URL(JWS Payload))). The signature should be generated using the algorithm mentioned in the JOSE header 'alg'. example: "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk" NotificationHeaders: required: - sender_code - timestamp type: object description: JSON object allOf: - properties: sender_code: type: string description: Registry code of the sender (e.g. provider or payer) example: "PROVIDER01@HCX01" timestamp: type: string description: Unix timestamp when the request is sent. example: "1629057611000" recipient_type: type: string enum: ["participant_code", "participant_role", "subscription"] description: The notification will be sent to a group of participants. To easily define the list we use role or codes or subscriptions. This property will help to understand the type of identifiers given in `recipients` property. recipients: type: array items: type: string description: >- The recipients will be identified based one of the below using `recipient_type`. `code`: Participant code of the recipient(s) of the notification. Could be one or more based on the need. `role`: Participant role of the recipient(s) of the notification. `subscription`: list of subscription_ids (at least one). it is mandatory for use_case category notifications. correlation_id: type: string description: Unique id for all notifications (trigger & dispatches) that are involved in processing notification trigger and dispatching to the recipients. expiry: type: string description: The time from when this notification will be invalid. example: "54539485304" NotificationRequest: required: - payload type: object description: JSON object allOf: - $ref: '#/components/schemas/NotificationJWSPayload' ListRequest: type: object description: JSON object explaining about the request filters, limits of the notification master list or the subscription list. properties: filters: type: object description: Filters to apply and get the required notification master list or the subscription list. limit: type: number description: Max number of notification master list or the subscription list to return in the response. example: 10 offset: type: number NotificationTopicListResponse: type: object description: The notification master list response object. properties: timestamp: type: string description: Unix timestamp when the response is sent. example: "1629057611000" notifications: type: array items: $ref: '#/components/schemas/NotificationTopic' count: type: number description: Total number of master list notifications defined at HCX gateway with the given request filter. example: 1 SubscriptionListResponse: type: object description: The subscription list response object. properties: timestamp: type: string description: Unix timestamp when the response is sent. example: "1629057611000" subscriptions: type: array items: properties: subscription_id: type: string description: Unique identifier of the notification subscription. example: "SUBSCRIPTION01@HCX01" status: type: number example: 1 topic_code: type: string description: Unique notification identifier from HCX gateway using the master list. example: "NOTIFICATION@HCX01" sender_list: type: array description: The list of sender to which the subscription request will be sent to approve or reject. items: type: string example: "PAYOR01@HCX01" count: type: number description: Total number of master list notifications defined at HCX gateway with the given request filter. example: 1 StandardErrorResponse: required: - error - timestamp type: object properties: timestamp: type: string description: Unix timestamp when the response is sent. example: "1629057611000" error: $ref: 'https://raw.githubusercontent.com/hcx-project/hcx-specs/v0.9/API%20Definitions/openapi_hcx.yaml#/components/schemas/Error' StandardSuccessResponse: required: - timestamp type: object properties: timestamp: type: string description: Unix timestamp when the response is sent. example: "1629057611000" subscription_id: type: string description: Unique identifier of the notification subscription. example: "SUBSCRIPTION01@HCX01" status: type: number example: 1 JOSEHeader: required: - alg type: object description: JSON Web Signature header as per RFC7515. For the current version, this is proposed to be fixed to {"alg":"RS256"} properties: alg: type: string enum: ["RS256"] additionalProperties: false NotificationTopic: type: object properties: title: type: string description: The title of the notification example: "Payer Downtime" description: type: string description: The details about the notification. example: "A notification about the Payer System Downtime. This information will be useful for all participants." sender: type: array description: List of roles who can send this notification. items: type: string example: ["payor"] recipient: type: array description: List of roles who can subscribe to this notification. items: type: string example: ["provider"] topic_code: type: string description: Unique code for the notification topic example: "NOTIFICATION@HCX01" category: type: string description: Category of the notification as detailed above - network (broadcast & target), participant, use_case example: network priority: type: number description: 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 template: type: string description: Message template to be used to create the message that is to be sent as part of the notification. NotificationSubscription: type: object properties: topic_code: type: string description: Unique notification identifier from HCX gateway using the master list. example: "NOTIFICATION@HCX01" sender_list: type: array description: The list of sender to which the subscription request will be sent to approve or reject. items: type: string example: "PAYOR01@HCX01" securitySchemes: bearer_auth: type: http scheme: bearer bearerFormat: JWT