Other

Notification on_subscribe

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

As a BSP you implement this path on your host, registered through on_notification_url, and receive a push whenever a workflow event occurs for a subscribed ABHA id: preauth_request (queued, processing), preauth_response (approved, rejected), claim_request, claim_response, payment_notice (paid, pending) and communication (information_required). The NHCX-side operation is invoked with hvalues senderid, receiverid, correlationid and status required, and workflowid, source, api_caller_id, call_type and usertoken optional. It sits outside the workflow-code sequence; domain_values may carry x-hcx-workflow_id, x-hcx-correlation_id, x-hcx-status, x-hcx-action and amount fields.

### Preconditions

- An active subscription created via /v1/notification/subscribe for the ABHA id; Last-Linked-Wins means only the most recently linked app receives events. - The BSP callback exposed over HTTPS with TLS 1.2 or higher at the registered on_notification_url, validating the JWT from NHCX, verifying sender_code and rate-limiting. - For the NHCX-side operation: a NotificationOnSubscribePayload with request.abhaid (required) and optional request.domain_values, plus hvalues with senderid, receiverid, correlationid and status. - The ordinary preauth or claim exchange between hospital and payer has produced an event for that beneficiary.

### Postconditions

The NHCX-side operation returns HTTP 200 with a SubscribeResponse (timestamp, api_call_id, correlation_id, subscription_id, subscription_status active, replaced or expired, expiry, message); 400, 401, 403, 409 and 500 return a StatusSuccessResponse with the same descriptions as the subscribe table. On the BSP callback the delivered payload carries notification_id, topic_code, timestamp, subscriber.id, a human-readable message that can be shown directly to the user, and optional domain_values with x-hcx-* headers for audit or custom formatting. Nothing changes in the hospital-payer exchange; the notification is a forked copy of the outcome.

### Common mistakes

- Conflating the NHCX-side operation with your own callback and implementing only one of them. - Parsing domain_values to build the user message instead of displaying the message field; domain_values is optional and may be absent. - Reading status from the x-hcx-workflow_id description (approved, rejected, queued, processing), which is a documentation error; the example carries an identifier and status lives in x-hcx-status. - Assuming the subscription is still yours; a subscription_status of replaced means another app took the routing slot on login. - Accepting callbacks without validating the JWT or sender_code, or without TLS 1.2 or higher. - Treating the senderid and receiverid descriptions (payer id, hospital id) literally in the notification context; they are inherited boilerplate.

### 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](/docs/nhcx/v1/reference/notifications-and-patient-apps) of the NHCX integration specification.