> ## Documentation Index
> Fetch the complete documentation index at: https://developer.eka.care/llms.txt
> Use this file to discover all available pages before exploring further.

# Serve records on a fetch request

> Answer Eka's request for records you keep yourself: encrypt the FHIR bundle and push it.

## 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:

* You send the base64 FHIR bundle in the `data` field when you [link a care context](https://developer.eka.care/docs/hie-cm/workflows/link-care-context-hip.md).
* You upload records through the [Upload API](https://developer.eka.care/api-sdk/health-records/obtain-authorization.md).

Then you do not need this workflow.

## Before you start

* A client access token, sent as a Bearer token. See [Authorization](https://developer.eka.care/api-sdk/auth/getting-started.md).
* 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](https://developer.eka.care/docs/hie-cm/workflows/link-care-context-hip.md) or [Answer discovery and link old records](https://developer.eka.care/docs/hie-cm/workflows/hip-discovery-and-link.md).
* A webhook URL registered with Eka that can receive `abha.hip_data_fetch`, and the means to verify the [webhook signature](https://developer.eka.care/docs/webhooks/webhook-signature.md).
* 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](https://developer.eka.care/docs/hie-cm/care-contexts/ecdh-encryption.md), or Eka's ECDH endpoints. The library keeps your private key on your server. The [Ecdh encrypt](https://developer.eka.care/api-sdk/hie-cm/care-contexts/ecdh/encrypt.md) endpoint takes your private key in the request body.

## Sequence

```mermaid theme={null}
sequenceDiagram
  participant HIU
  participant Eka
  participant App as Your app
  HIU->>Eka: Data request under a granted consent
  Eka-->>App: webhook abha.hip_data_fetch
  App->>Eka: GET /abdm/v1/ecdh/keys
  App->>Eka: POST /abdm/v1/ecdh/encrypt
  App->>Eka: POST /abdm/v1/hip/care-context/data/on-fetch
  Eka->>HIU: Encrypted data
```

If you use the `abdm-ecdh` library, the two `/abdm/v1/ecdh/` calls run in your own code instead. [Encryption](https://developer.eka.care/docs/hie-cm/care-contexts/ecdh-encryption.md) shows the library's calls and their outputs.

## Steps

**1. Receive the fetch request**

Eka sends the [`abha.hip_data_fetch`](https://developer.eka.care/docs/hie-cm/webhooks/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](https://developer.eka.care/api-sdk/hie-cm/care-contexts/ecdh/keys.md). 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](https://developer.eka.care/api-sdk/hie-cm/care-contexts/ecdh/encrypt.md) 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](https://developer.eka.care/api-sdk/hie-cm/care-contexts/data-on-fetch.md). 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

| Field | From | Keep | For |
| - | - | - | - |
| `care_context_id` and its FHIR source | Your link call | As long as the care context is linked | Building the bundle when a fetch arrives |
| `transaction_id` | `abha.hip_data_fetch` | Until the last page is accepted | Every on-fetch call for this request |
| `key_information` | `abha.hip_data_fetch` | Until the last page is accepted | Encrypting each bundle |
| `private_key`, `public_key`, `nonce` | Your key material | Until the last page is accepted | Encrypting and the push's `key_information` |
| Plain-text checksum per bundle | You | Until the push is accepted | The `checksum` field |

## When it fails

> [!WARNING]
>
> Which of these codes each call returns is not yet confirmed. The codes come from the [errors page](https://developer.eka.care/docs/hie-cm/errors.md), matched by meaning. Log the code you actually receive.

Error responses carry `code`, `error` and `source_error`.

| Situation | Code | Do |
| - | - | - |
| Push body malformed or a field invalid | `ABDM-1006`, `ABDM-1010` | Fix the request against the reference page and resend |
| Transaction id unknown | `ABDM-1017`, `ABDM-1052` | Check you sent the `transaction_id` from the webhook |
| Consent expired or not granted | `ABDM-1061`, `ABDM-1062` | Stop; do not send data for this request |
| HIU unavailable | `ABDM-1033` | Retry later |
| Gateway timeout or dependent service down | `ABDM-1048`, `ABDM-1019` | Retry later |
| Your webhook did not answer within 5 seconds | No code; Eka retries the webhook | Acknowledge first, then build and push |
| Encryption fails or the HIU cannot decrypt | Not documented | Check the receiver key and nonce came from this webhook's `key_information` |

## Test it

The [testing page](https://developer.eka.care/docs/hie-cm/testing.md) 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](https://developer.eka.care/docs/hie-cm/care-contexts/ecdh-encryption.md)
* [ ] Return a non-`200` from your webhook once and confirm Eka retries


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.