Other

Notification subscribe

A Beneficiary Service Provider (PHR app) subscribes an ABHA id to notification topics; NHCX persists it synchronously, Last-Linked-Wins per ABHA id.

### Business purpose

Every other flow is a two-party exchange between hospital and payer. Notifications let a third party, the beneficiary through a PHR app, watch a claim move without being a sender or recipient on the underlying preauth or claim. The caller is a Beneficiary Service Provider (BSP), not a hospital or insurer; the persona label here is the nearest available. The subscription is what routes human-readable messages such as a preauth approval with amount and validity to the patient's app, giving beneficiaries transparency and reducing calls to the hospital desk.

### When to use

Call it on every beneficiary login (Subscribe-on-Login): the user authenticates with the ABHA address, the app checks its NHCX token, refreshes via the sessions endpoint if expired, then subscribes the ABHA id and stores the returned subscription_id. Because Last-Linked-Wins replaces any earlier app's subscription, resubscribe on each login rather than trusting a stored id. Most PHR apps need only topic_code workflow_events; network_events and participant_events are also defined. The call is synchronous and sits outside the workflow-code sequence; a fresh x-hcx-correlation_id is required per attempt.

### Preconditions

- ABDM M1 integration completed; BSP sandbox testing on hcxsbx.abdm.gov.in, certification and production registry onboarding. - An HTTPS callback endpoint with TLS 1.2 or higher registered as on_notification_url, and JWT capability. - Access token from the ABDM session token call (01-session/session-token.bru); sent as Authorization: Bearer with Content-Type application/json. - Body is a JWEPayload whose compact JWE carries protected headers alg RSA-OAEP, enc A256GCM, x-hcx-sender_code (your BSP code), x-hcx-recipient_code (NHCX gateway code), x-hcx-timestamp (ISO 8601) and a unique x-hcx-correlation_id, plus the subscribe JSON: subscription_id, topic_code array, recipient_code, subscriber.id (ABHA id), on_notification_url and optional expiry. - Explicit user consent obtained before subscribing.

### Postconditions

NHCX decrypts the request with its private key, validates headers and payload, persists the subscription with Last-Linked-Wins per ABHA id and returns the subscription state synchronously: HTTP 200 with a SubscribeResponse carrying timestamp, api_call_id, correlation_id, subscription_id, subscription_status (active, replaced or expired), expiry and message. Thereafter, when a hospital submits a preauth or claim with that ABHA id and the payer responds, NHCX pushes a notification (notification_id, topic_code, timestamp, subscriber.id, a displayable message and optional domain_values) to the registered callback. Errors: 400 validation, 401 sender not authorised, 403 sender not permitted, 409 duplicate correlation id, 500 decryption or persistence failure.

### Common mistakes

- Reusing x-hcx-correlation_id across attempts or retries, which returns 409 (the API reference defines 409 as replay detection, not an existing-subscription conflict). - Subscribing once and trusting the stored subscription_id; another app's login silently replaces it (subscription_status replaced). - Sending it to the exchange host, https://apisbx.abdm.gov.in/hcx, where the other /v1 calls go. The notification integration guide gives the portal host: https://hcxsbx.abdm.gov.in/v1/notification/subscribe. - Sending the token on bearer_auth. This call reads it from Authorization: Bearer. - Sending protocol headers in the clear rather than inside the JWE protected header. - Using the NHCX client-credentials token endpoint instead of the ABDM gateway sessions endpoint. - Subscribing silently without consent or without showing subscription status in settings.

### Best practices

- Subscribe on every login and refresh the token before its 100-minute expiry; store access_token encrypted and never log the secret. - Generate a fresh UUID correlation id per subscribe attempt, including retries; retry 500s with backoff, regenerate the token on 401, check the registry on 403. - Subscribe only to the topics you need, typically workflow_events. - Secure the callback: HTTPS with TLS 1.2 or higher, validate the JWT from NHCX, verify sender_code, rate-limit. - Display the message field directly to users; treat domain_values as optional audit data and read status from x-hcx-status, not the workflow id description.

### Related scenario

A beneficiary opens a PHR app and logs in with the ABHA address ravi@abdm. The app confirms its NHCX token is valid, then posts /v1/notification/subscribe with subscription_id sub_ravi_001, topic_code workflow_events, its BSP code and its on_notification_url, under a fresh correlation id. NHCX replies 200 with subscription_status active. Later that day a hospital submits a preauth for the same ABHA id on /v1/preauth/submit and the payer approves it on /v1/preauth/on_submit; NHCX pushes a notification to the app's callback reading that the preauthorisation was approved for Rs. 50,000 with its validity dates, which the app displays as-is.

### Specification

Chapter [Notifications and patient apps](/docs/nhcx/v1/reference/notifications-and-patient-apps) of the NHCX integration specification.