Patient app: acknowledge a notification subscription

BSP-side subscription acknowledgement; the same name denotes the callback where NHCX pushes claim-event notifications for a subscribed ABHA ID.

Business purpose

Two things share this name. The API reference defines an NHCX-side operation (operationId onSubscribe) that takes a NotificationOnSubscribePayload with the beneficiary's abhaid, optional domain_values and plain header values, and returns a SubscribeResponse; it is described as the BSP-side subscription persistence acknowledgement. The integration guide uses the same path on the BSP's own host as the callback where NHCX delivers notifications. Together they complete the beneficiary-facing loop: the patient's app learns, in plain language, that a preauth was approved, a claim adjudicated, a payment made or information requested. The caller is a Beneficiary Service Provider; the persona label is the nearest available.

When to use

A beneficiary app hosts this path to receive notifications for the ABHA IDs it subscribed. NHCX calls it when a pre-authorisation, claim, payment or query event happens.

Preconditions

• An active subscription exists for the ABHA ID, made through /v1/notification/subscribe.
• Your callback runs over HTTPS with TLS 1.2 or higher, at the registered on_notification_URL.
• You check the token NHCX sends and its sender code.

Postconditions

Each notification carries a message you can show the user as it is. Nothing changes in the exchange between hospital and payer.

Common mistakes

• Building the user message from domain_values, which may be missing, instead of showing message.
• Reading the status from x-hcx-workflow_ID. It lives in x-hcx-status.
• Assuming the subscription is still yours after it shows replaced.
• Accepting calls without checking the token or the sender code.

Best practices

• Display message verbatim; keep domain_values for audit logging or advanced formatting only.
• Validate the JWT and sender_code on every inbound push, enforce TLS 1.2 or higher and rate limiting.
• Map event types (preauth_response, claim_response, payment_notice, communication) to in-app timelines using x-hcx-action and x-hcx-status.
• Show subscription status in settings so a replaced subscription is visible to the user; resubscribe on next login.
• Keep the endpoint fast and idempotent on notification_ID.

Related scenario

A PHR app has subscribed ravi@ABDM to workflow_events. A hospital submits a claim on /v1/claim/submit for that beneficiary and the payer adjudicates it on /v1/claim/on_submit. NHCX forks the outcome to the app's registered on_subscribe callback with topic_code workflow_events, a message stating the claim was approved with the amount, and domain_values including x-hcx-action claim_response and x-hcx-status response.complete. The app validates the JWT and sender_code, shows the message on the patient's timeline, and when the payer later sends a payment notice on /v1/paymentnotice/request the next push reads paid.

Specification

Chapter Notifications and patient apps of the NHCX integration specification.