Integration Managing payloads

Managing Payload

To ensure that sensitive information in the actual domain objects is not accessible even to the HCX, the protocol requires the payload defined by the domain data specifications to be encrypted using a separate asymmetric encryption key of the final recipient established at the time of participant onboarding into the registry. The API then carries the encrypted value of the payload.

The payload encryption is expected to be performed using JSON web encryption RFC7516 as per the algorithm and enclosed values fixed in the protected headers section above. At this point in time, no unprotected headers are envisioned in the HCX Protocol. We also do not envision multiple recipient delivery in the current version of the HCX protocol.

More information about payload encryption/decryption is available in the Message Security section in the specifications.

The Payers/Providers system needs to perform the following steps when a payload is received or to create a payload. The HCX team has also developed a Mock Payer/Provider system which also performs the same steps as given below:

Processing incoming payloads

1. Ensure Request and Response structure for APIs will follow HCX Specifications as done in HCX APIs.
2. Authenticate the API caller (HCX) validity using the bearer token in the HTTP request.
3. Decode the header in the payload and do HCX Protocol Header validation as per the document Protocol Errors
4. Verify signature and Decrypt the payload using your private key (as the sender is expected to encrypt the payload using your public key). You can use your respective tech stack libraries for JWE to perform this step.
5. Perform schema validations for the decrypted ciphertext which contains FHIR Object in JSON format as per Swasth FHIR implementation.
6. Validate the FHIR object(JSON) for Business validations.
7. Create the acknowledgement response to be sent back to HCX. Schema for response can be found here
   Following operations will be performed to form the response body for the API call received:
   • timestamp is generated while sending the response
   • correlation_id and api_call_id are extracted from the payload after decoding the header from the payload

Sample Success Response:

{
  "timestamp": "2022-02-11T09:43:35.156+0000",
  "correlation_id": "1661b567-ebdf-491f-a29b-f49ab1c0a09c",
  "api_call_id": "8fa9a8bc-aab4-4260-927d-0186456bfd9a"
}

8. Perform the business logic with the FHIR object received in the incoming request payload. This step would be specific to your platform and may require mapping incoming FHIR payload attributes to your internal data structure. Receive the final response from your internal system and use the steps below to send the corresponding callback response to the sender of the request.
9. Create the encrypted payload for on action call to be sent to the sender as detailed in the next section.
10. API request body for on_action can be one of the following schemas (depending on the nature of the response):
    • #/components/schemas/JWEPayload
    • #/components/schemas/ProtocolResponse
    • Refer to HCX API specficications for more details on the schema.

Formulating outgoing payloads

A Request body for on_action calls needs to be created. Creating the HCX Protocol headers for response would need a few details from the protocol header of the incoming request, hence please ensure that it was preserved. The following steps need to be performed to create the payload for the callback response:

1. Update sender id (x-hcx-sender_code) with your id.
2. Update the recipient id with the id of the sender (x-hcx-sender_code) of the incoming request.
3. Assign a unique id (uuid) to x-hcx-api_call_id.
4. Copy correlation id (x-hcx-correlation_id) from the incoming request header.
5. x-hcx-status shall be one of response.complete, response.error, response.partial or response.redirect.
   1. In the case of response.complete and response.partial the request body will follow the below schema
      • #/components/schemas/JWEPayload schema
   2. In case of response.error, the request body will follow one of the below schemas
      • #/components/schemas/JWEPayload for errors related to the payload during business evaluation (after successful decryption)
      • #/components/schemas/ProtocolResponse which will have error details in it. This schema will be used for Protocol Header related errors and unable to access the ciphertext due to any reasons.
   3. In case of response.redirect, the request body will follow the below schema
      • #/components/schemas/ProtocolResponse
      • Also a redirect_to header will be added to the protocol header
6. Payload for the request body for the callback (on_check/on_submit) will be a sample FHIR object as per the specifications. Eg. if coverageeligibility/check call has been made with payload as CoverageEligibilityRequest document then the response should have the CoverageEligibilityResponse document in the coverageeligibility/on_check call to the HCX > Provider
7. Encrypted and sign the response data and protocol headers with Recipient's Public Key which can be accessed using HCX Registry APIs.
8. A new JWE payload is created with the headers and payload created in the previous steps.
9. If not already available, create the Bearer token using your Username and Password shared during the onboarding process. Below is the curl snippet for token generation.

curl --location --request POST 'https://staging-hcx.swasth.app/auth/realms/swasth-health-claim-exchange/protocol/openid-connect/token' \
--header 'content-type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=registry-frontend' \
--data-urlencode 'username=<REGISTERED_EMAIL>' \
--data-urlencode 'password=<PASSWORD>' \
--data-urlencode 'grant_type=password'

10. Post the callback to the HCX using the Bearer token and payload.