Skip to main content

Patient app: subscribe an ABHA number to notifications

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

POST/v1/notification/subscribe

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 every time a beneficiary logs in to your app. The last app to subscribe an ABHA ID wins, so do not trust a stored subscription.

Preconditions

  • You have a valid access token, sent in the Authorization header.
  • Your callback URL is registered over HTTPS, with TLS 1.2 or higher.
  • The user has agreed to receive notifications.
  • The body is encrypted and carries a new x-hcx-correlation_ID.

Postconditions

NHCX saves the subscription and answers 200 with a subscription_ID and its status. From then on, claim events for that ABHA ID are pushed to your callback.

Common mistakes

  • Reusing a correlation ID on a retry, which returns 409.
  • Subscribing once and assuming it still holds after another app logs in.
  • Sending it to the exchange host instead of https://hcxsbx.abdm.gov.in/v1/notification/subscribe.
  • Sending the token on bearer_auth instead of Authorization.

Best practices

  • Subscribe on every login and refresh the token before its 20-minute (1200-second) 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 of the NHCX integration specification.

Protected header

These fields go in the JWE protected header of payload, not as HTTP headers. Building and sending a JWE shows how to prepare and encrypt the payload, and Receiving a callback how to decrypt one.

algstringRequired

Key management algorithm. Always RSA-OAEP-256: the content key is wrapped with the recipient's RSA public key.

Example RSA-OAEP-256

encstringRequired

Content encryption algorithm. Always A256GCM.

Example A256GCM

x-hcx-sender_codestringRequired

Your participant code. Mandatory on the envelope.

Example phr-app-xyz@bsp

x-hcx-recipient_codestringRequired

The recipient's. For a provider, the processor code from the policy lookup. Mandatory on the envelope.

Example nhcx-gateway@hcx

x-hcx-timestampstringRequired

The time the message was made. Timestamp gives the format. Mandatory on the envelope.

Example <iso timestamp>

x-hcx-correlation_idstringRequired

The thread that ties a request to its answers. The correlation ID rule says when to reuse it. Mandatory on the envelope.

Example <uuid>

Body

payloadstring
_payload_plaintextobject
_payload_plaintext.subscription_idstring
_payload_plaintext.topic_codestring[]
_payload_plaintext.recipient_codestring
_payload_plaintext.subscriberobject
_payload_plaintext.subscriber.idstring
_payload_plaintext.on_notification_urlstring

Responses

200

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.

timestampstring
api_call_idstring
correlation_idstring
subscription_idstring
subscription_statusstring
expirystring
messagestring