Skip to main content

​
In short

  • Acknowledge abha.hiu_data_push within 5 seconds, then decrypt.
  • Decrypt each entry with your stored private_key and nonce.
  • Report each entry’s result with Push FHIR parsing status.
  • If Eka stores the data for you, read the records from the records product instead.

​
When to use this

The patient has granted a consent you raised in Request a patient’s consent as a HIU, and you manage the data on your side. Each HIP encrypts the approved records with your public keyset and Eka delivers them to you on a webhook. This workflow decrypts them and tells Eka which care contexts you could parse. If Eka stores the data for you, nothing arrives on a webhook. Read each approved care context with Retrieve Health Records in the records product, passing the care_context_id from Consent Details as the identifier. That call belongs to the records product and is documented there.

​
Before you start

  • A bearer token for the API. See Authorization.
  • Your public keyset registered, and the matching private_key and nonce stored on your side. See the keyset steps in Request a patient’s consent as a HIU.
  • A granted consent, with its consent_id and the approved care_contexts[].id.
  • A webhook endpoint registered with Eka that verifies the Eka-Webhook-Signature header. See Webhook signature.
  • A way to decrypt: either the Ecdh decrypt call, or the abdm-ecdh library in Go, Python or Java.

​
Sequence

​
Steps

1

Receive the push and acknowledge it

Eka sends abha.hiu_data_push when a HIP pushes records for your consent. Verify the signature and reply 200 within 5 seconds; Eka retries on any other status. Decrypt after you reply, so the 5 seconds are not spent on decryption.From data, keep:
  • consent_id and transaction_id: you send both back in the acknowledge step. The webhook carries a top-level transaction_id and a data.transaction_id; which of the two fields on-push expects is not yet confirmed.
  • entries: one per care context, each with care_context_id, content (the encrypted FHIR bundle), checksum and media (application/fhir+json).
  • key_information: the sender’s key material, with dh_public_key.key_value and nonce.
  • hip_id, abha_address and oid: which HIP and which patient the records belong to.
Match consent_id against the consents you raised.
2

Decrypt each entry

Call Ecdh decrypt once per entry, or decrypt locally with the abdm-ecdh library. Map the fields like this:key_information.dh_public_key is the HIP’s (sender’s) public key; your own key is the private key you registered with your keyset.The response carries decrypted_data, the FHIR bundle as plain text. Hash the decrypted bundle and compare the result with entries[].checksum: the checksum is computed over the plain-text FHIR data, not the encrypted content. Parse the bundle as JSON.
3

Report the parsing status

Call Push FHIR parsing status with:
  • consent_id.
  • The transaction_id from the webhook. Which of the two fields is not yet confirmed.
  • One status_response item per entry, with care_context_id, success (true if you decrypted and parsed it), and a description when it failed.
Eka returns 202 Accepted.

​
State you must persist

​
When it fails

Which of these codes each call returns is not yet confirmed. The codes come from the errors page, matched by meaning. Log the code you actually receive.
Error responses carry code, error and source_error (code, message). Codes are listed on the errors page.

​
Test it

The testing page has the sandbox base URL, credentials and the happy path for every journey. Sandbox base URL: https://api.dev.eka.care.
  • Run Request a patient’s consent as a HIU to a granted consent
  • abha.hiu_data_push arrives; your endpoint replies 200 within 5 seconds
  • Each entry decrypts to a FHIR bundle with Ecdh decrypt and with the abdm-ecdh library, and both give the same result
  • On-push with every entry success true returns 202
  • Decrypt with a wrong private key; report that entry with success false