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
- The inbox with acknowledgement and deduplication. Nothing works without a reliable receiver.
- The correlation store, handling both directions from the start.
- The outbox with retry and token refresh.
- 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.
