Message Structure

Components of message and their details

Message Structure

To facilitate safe, secure, and reliable message exchanges through HCX, its message payload needs to be designed in a manner that separates the actual use case-specific information (payload) from transport and generic domain-specific information (headers). To achieve this, HCX messages can be structured in line with JWE tokens as below (value in bracket are the corresponding JSON keys as per JWE):

1. Protected headers (protected) - A set of attributes that provide transport, security, message integrity and summary information about the message being exchanged.

2. Encrypted Payload (ciphertext) - 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. Signature (tag) - Digital signature on the protected header and the payload of the message to ensure its integrity.

4. Other JWE elements like iv (Initialisation Vector for the algorithm), , cryptographic mechanisms used in JWE encrypts and provide integrity protection to encrypted payload and protected headers using Authenticated Encryption with Associated Data (AEAD), hence additional signatures are not needed for message integrity protection.aad (additional authentication data), and encrypted_key (Content Encryption Key)

HCX expects the resulting JWE token to be JSON serialised. The following subsections detail each of these message elements:

Protected Headers

Protected headers contain information that helps exchanges to identify senders, receivers of the message, perform integrity checks, audits and routing functionality. Header values are posted in clear and never contain any Personally Identifiable Information (PII) about the patient. HCX protocol uses JWE 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:

Registered JOSE Headers

JSON Web encryption header as per RFC7516. For HCX V1, this is proposed to be fixed to:

{"alg":"RSA-OAEP","enc":"A256GCM"}

HCX Protocol Headers

Used as private headers as per RFC7516 section 4.3. Please note that all the parameter names are appended with “x-hcx-” to avoid a collision.

The following table provides the protocol related header elements in the claims exchange:

Name	Description	Type	Additional Properties
x-hcx-sender_code	Registry code of the sender (e.g. provider or payer)	String	Mandatory
x-hcx-recipient_code	Registry code of the recipient (e.g. provider or payer)	String	Mandatory
x-hcx-api_call_id	Sender generated unique id for each originating request. All senders (providers & payors) must generate and set a unique value to the x-hcx-api_call_id protocol header in all the API calls to the HCX gateway. This header will be useful in tracking individual HTTP API calls to HCX, request level issue resolution with/at HCX and for debugging.	String	Mandatory
x-hcx-correlation_id	Unique id for all messages (requests & responses) that are involved in processing of one cycle (like coverage eligibility, pre-auth, claim, or payment notice cycle). The participant system sending the originating request of the cycle must set the x-hcx-correlation_id in the initial API call and the HCX gateway shall forward the same correlation id to the recipient of the request. The recipient must set the same correlation id in the response API call and in other API calls related to the original request (e.g. communication request, forward/redirect requests). And the same correlation id must be sent in all subsequent API calls (related to the same cycle). In case of status request API call, this header should have the correlation id of the request for which the status is being requested for.	String	Mandatory
x-hcx-workflow_id	Optional identifier to track all the messages related to a single hospitalisation episode. The workflow id spans over multiple cycles of message exchanges within a single admission/case. This is an optional header that can be set by providers to the same value for all requests (coverage eligibility check, preauth, claim, etc) related to a single admission/case. And when the workflow_id is sent by the originating provider, all other participant systems (payors) must set the same workflow id in all API calls (responses, forwards/redirects, payment notices, etc) related to the workflow.	String	Optional
x-hcx-timestamp	Unix timestamp of the message while sending	datetime	Mandatory
x-hcx-debug_flag	Request to the server to include debug information. Useful in the time of integration testing and prod debugging. However, server(s) may choose to ignore this flag based on their policy.	ENUM - Error - Info - Debug	Optional
x-hcx-status	Operational status of the message. Depending on the leg of the message it would be: request.queued: when the request is submitted to the HCX gateway but the gateway has not yet forwarded the request to the intended recipient. request.dispatched: when the request is successfully dispatched by the HCX gateway to the intended recipient. response.complete: when the recipient is sending a successful final response to the sender. This marks the completion of the request and cycle (in the case when the response is for the originating request of the cycle). response.partial: when the recipient is sending a partial response to the sender. Senders should expect more responses when a message with this status is received. response.error: when the recipient wants to communicate an error to the sender. Details of the error should be provided in the x-hcx-error_details protocol header (and also within the FHIR resource being returned, if applicable). response.redirect: when the recipient wants to send a redirection instruction to the sender. The header x-hcx-redirect_to must be set when this status is used (to inform the sender to whom the request must be redirected to).	String	Optional
x-hcx-redirect_to	Expected to be set when the x-hcx-status value is "response.redirect". The value should be the registry code of the recipient to whom the request has to be redirected to.	String	Optional
x-hcx-error_details	Expected to be used for providing details of the status. It Will be especially useful in scenarios where Operational status indicates an irrecoverable error. Key elements of this object are: code: error, info, debug code from the system - expected to be namespaced for better readability. Mandatory. message: Short description of the detail. Mandatory. trace: Long description supporting the Code	JSON Object - E.g. {code: “bad.input”, message: “Provider code not found”, trace: “”}	Optional
x-hcx-debug_details	Expected to be used for providing details of the status. It Will be especially useful in debugging scenarios Key elements of this object are: code: error, info, debug code from the system - expected to be namespaced for better readability. Mandatory. message: Short description of the detail. Mandatory. trace: Long description supporting the Code	JSON Object - E.g. {code: “bad.input”, message: “Provider code not found”, trace: “”}	Optional

HCX Domain Headers

JSON object containing a map of domain-specific header values as proposed in domain data specifications. E.g. For claims use cases, domain specs may decide to populate the total claimed amount, list of diagnostics/procedures. Please note that all such parameter names must follow the naming convention x-hcx-<use_case_name>-<parameter_name>, where

• use_case_name = short name (<16 chars) given to the use case by domain working group, it is advisable to keep it the same as the one in API’s URI path

• Parameter_name = short name (<32 chars) given to the parameter

Domain Header Name	Description
x-hcx-insurance_plan_url	This domain header has to be returned in the successful response to coverage eligibility check API. The value should be a url to the InsurancePlan object with the details on benefits, required documents and other important information to submit claims.

Therefore the protected headers will be:

Protected Headers = (Registered JOSE headers) U (HCX Protocol Headers) U (HCX Domain Headers)

Payload

Use case-specific base64 encoded, encrypted payload as defined in Domain Data specifications. This can be thought of as a private claim in JWT terminology. JSON web encryption as defined in RFC7516 to be used for encrypting the payload with “alg” and “enc” as defined in the JOSE header above.

E.g. In the current cashless claims scenario, domain working groups have decided the payload to be an FHIR bundle of the appropriate type. Therefore the payload will be an encrypted FHIR bundle as defined in the domain data specs.

Signatures

As per RFC7516, cryptographic mechanisms used in JWE encrypts and provides integrity protection to encrypted payload and protected headers using Authenticated Encryption with Associated Data (AEAD), hence additional signatures are not needed for message integrity protection.

Follwing section provides details of the API structure and the API responses.