Skip to main content

​
In short

  • Use this only if you link care contexts without sending their FHIR data to Eka.
  • Eka sends abha.hip_data_fetch; acknowledge it within 5 seconds.
  • Encrypt each bundle for the HIU, then push it with on-fetch.
  • Send back the transaction_id from the webhook.

​
When to use this

You linked care contexts without sending their FHIR data to Eka, so you hold the records yourself. When a Health Information User (HIU) requests those records after the patient grants consent, Eka sends you a webhook. You build the FHIR bundles, encrypt them for the HIU, and push them back. Eka serves the data itself, and you never receive this webhook, in two cases: Then you do not need this workflow.

​
Before you start

  • A client access token, sent as a Bearer token. See Authorization.
  • Your facility onboarded as a Health Information Provider (HIP), with its HIP ID.
  • Care contexts linked without data, through Link a care context as a HIP or Answer discovery and link old records.
  • A webhook URL registered with Eka that can receive abha.hip_data_fetch, and the means to verify the webhook signature.
  • A way to produce an ABDM-compliant FHIR bundle for each care context you linked.
  • A choice of how to encrypt: the open-source abdm-ecdh library in your own code, described in Encryption, or Eka’s ECDH endpoints. The library keeps your private key on your server. The Ecdh encrypt endpoint takes your private key in the request body.

​
Sequence

If you use the abdm-ecdh library, the two /abdm/v1/ecdh/ calls run in your own code instead. Encryption shows the library’s calls and their outputs.

​
Steps

1

Receive the fetch request

Eka sends the abha.hip_data_fetch webhook. Acknowledge it with HTTP 200 within 5 seconds; Eka retries on any other status. Do the rest of the work after you acknowledge.From data, keep:
  • care_contexts: the ids of the care contexts to send, the same ids you linked.
  • hi_types: the health information types the HIU asked for.
  • key_information: the HIU’s key material. You need dh_public_key.key_value, dh_public_key.expiry and nonce.
  • transaction_id: you send it back in the push.
  • abha_address, oid, partner_patient_id and hip_id: to find the patient and for the push headers.
2

Generate your key material

Call Ecdh keys. The response carries private_key, public_key and nonce for your side of the exchange.
3

Encrypt each care context's bundle

Build the FHIR bundle for each id in care_contexts. Call Ecdh encrypt once per bundle with:
  • plain_text_data: the FHIR bundle as a string.
  • sender_private_key, sender_public_key, sender_nonce: your key material from the previous step.
  • receiver_public_key: key_information.dh_public_key.key_value from the webhook.
  • receiver_nonce: key_information.nonce from the webhook.
The response carries encrypted_data and key_to_share.Compute a checksum of the plain-text bundle before you encrypt it; the push needs it.
4

Push the encrypted data

Call Push care context data to HIU. Send the patient’s oid in X-Pt-Id, your patient id in X-Partner-Pt-Id and your HIP ID in X-Hip-Id. In the body send:
  • transaction_id from the webhook.
  • entries: one per care context, each with care_context_id, content set to encrypted_data, media set to application/fhir+json, and checksum.
  • key_information: your side of the exchange, with crypto_alg ECDH, curve Curve25519, dh_public_key (key_value, expiry, parameters) and nonce set to your nonce.
  • page_number and page_count.
The call 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.

​
Test it

The testing page has the sandbox base URL, credentials and the happy path for every journey.
  • Link a care context without data, then raise a consent request for it from a sandbox HIU and receive abha.hip_data_fetch
  • Encrypt one bundle with GET /abdm/v1/ecdh/keys and POST /abdm/v1/ecdh/encrypt, push it, and get 202 Accepted
  • Repeat with the abdm-ecdh library and compare the result
  • Round-trip the library on its own first: generate two key sets, encrypt with one, decrypt with the other, as in Encryption
  • Return a non-200 from your webhook once and confirm Eka retries