NHCX Asynchronous Callbacks: Architecture Requirements for an HMIS

Almost every module in a hospital information system is synchronous. A user acts, the system calls something, an answer comes back, the screen updates. NHCX does not work that way, and the mismatch is an architectural change rather than a client library.

What actually happens when you submit a claim

You send a pre-authorization. You receive 202 Accepted — which means the exchange has taken custody of the message, not that anything has been decided. Some minutes later the payer's response arrives at your server as a fresh inbound request, carrying a reference that ties it back to what you sent.

Three consequences follow immediately, and each of them is a component:

• You cannot block a user on the answer, so the claim needs a state model rather than a return value.
• You must be reachable from the internet to receive it — see the on-premise callback problem.
• You must be able to match an inbound message to the outbound one it answers, which means storing the correlation yourself.

The outbox

Submissions should be written to a durable outbox and sent from there, not sent inline from the request handler. Two reasons. First, the exchange may be briefly unavailable and a claim must not be lost because a user's HTTP request timed out. Second, tokens expire — a submission that fails on an expired token should be retried after refresh rather than surfaced to a claims operator as an error they cannot act on.

The outbox row is also where you record what you sent, byte for byte. When a payer later disputes the content of a claim, that record is the answer.

The inbox, and why deduplication matters

Inbound responses land on your callback endpoint. Acknowledge them immediately and process them afterwards — the acknowledgement is time-bounded, and a receiver that does heavy work before responding will eventually fail that window under load.

Write the message to an inbox table first, keyed so that a repeat delivery is recognised. Redelivery happens. If your handler applies an adjudication twice because the same callback arrived twice, you have created a reconciliation problem that is genuinely unpleasant to unwind.

This is the point where the acknowledgement stops being a technical detail and becomes a commitment: your receiver's uptime is now contractual. It is not a background job that can be down for an afternoon.

Correlation is not as simple as it looks

The obvious model — inbound reference equals outbound reference — is right for the straightforward path and wrong in two important cases.

Payer-initiated messages arrive on their own reference. When a payer raises a query against your pre-authorization or claim, that message is not a reply to yours in the protocol sense; it starts its own conversation. If you correlate strictly against your outbound references, payer queries look like unsolicited traffic and get dropped — and a dropped query becomes a rejected claim.

Your reply must reuse the inbound reference. When you answer a payer's query, the response carries the reference of the message you are answering, not a fresh one. Send a new reference and it is rejected, correctly, because there is nothing for it to attach to.

The practical shape is a correlation store that maps references to claims in both directions, and treats an inbound message with an unknown reference as a new conversation to be routed rather than an error to be logged.

Claim state, properly modelled

A claim moves through pre-authorization, query, enhancement, discharge, final claim, reprocessing, cancellation and payment. Each transition is driven by a message, in either direction, and several are optional. A status enum with six values will be wrong within a month.

Model it as a state machine with an event log: every inbound and outbound message appended, current state derived. That gives you three things for free — an audit trail, the ability to replay, and a claim history screen that shows an operator exactly where the claim is and what it is waiting on.

What to build first

1. The inbox with acknowledgement and deduplication. Nothing works without a reliable receiver.
2. The correlation store, handling both directions from the start.
3. The outbox with retry and token refresh.
4. The claim event log, before the first flow goes live — retrofitting history you did not record is impossible.

None of this is exotic; it is standard asynchronous messaging. The reason it is worth calling out is that it rarely exists in an HMIS already, and it is discovered late by teams who scoped NHCX as a set of API calls. If your team has done ABDM work, the callback handling will feel familiar — the claim state machine will not.

If you are scoping NHCX for a hospital information system, our healthcare interoperability team has built the full flow end to end against the sandbox. For the architectural half — the asynchronous layer, the callback path, the claim state model — see our healthcare software product engineering practice. Talk to our team to walk through your product.