Skip to main content

Adapter

Task callback (internal variant) (adapter)

Internal twin of /v1/task/on_submit (hcxOnTaskPostInternal): the payer Task bundle wrapping the ClaimResponse outcome of a reprocess or cancel.

POST/internal/v1/task/on_submit

### Business purpose

This is the internal-path form of the callback that closes a reprocess or cancellation. The OpenAPI lists it with the same description and bare object body as the public callback and distinguishes it only by the operationId suffix. Its role is unchanged: deliver the payer's final, auditable decision on an appeal, or confirmation of a preauth cancellation, in a Task bundle whose Task.output references a ClaimResponse that hospitals can parse with their normal adjudication logic.

### When to use

Same as the public callback: after acknowledging and re-adjudicating a Task, the payer posts a Task bundle with status completed and Task.output referencing the ClaimResponse, under the original correlation id, with workflow 252, 253 or 254 (or PC02 for cancellation) and a responder status. The specifications do not say when the internal path is used in preference to the public one.

### Preconditions

- Inbound Task decrypted, correlation id captured, 202 acceptance returned within 30 seconds. - Registered payer with a valid Bearer token and the provider's certificate. - Task bundle with Task.status completed and Task.output[0].valueReference resolving to a ClaimResponse entry in the bundle. - Protected header echoing the request's correlation id with a fresh api_call_id, IST timestamp, outcome workflow id and responder status. - Confirmation that the internal route is the intended one.

### Postconditions

Returns 202 Accepted with the StatusSuccessResponse envelope, or 400, 404 or 500 in the same shape; the bundle is forwarded to the provider, which acknowledges within 30 seconds, extracts the ClaimResponse from Task.output and closes the appeal branch. The decision is final within the workflow context; approval leads to payment workflows 30, 31 and 33. No additional behaviour is documented for the internal variant.

### Common mistakes

- Expecting a different envelope or relaxed validation; none is documented. - Sending a standalone ClaimResponse bundle rather than a Task wrapper, or minting a new correlation id (NHCX-1010). - Provider side: reading the ClaimResponse from Bundle.entry directly, or treating outcome complete as approval without checking the adjudication reason. - Using an unconfigurable path that cannot switch between public and internal forms.

### Best practices

- Share the public callback's bundle builder; only the path differs. - Acknowledge the inbound Task first, re-adjudicate asynchronously, then post. - Provider: reuse the claim ClaimResponse parser, reached via Task.output[0].valueReference.reference. - Idempotent handling on correlation id; fresh api_call_id and IST timestamp on the callback.

### Related scenario

A payer platform reviewing the taskhcxservice specification sees hcxOnTaskPost and hcxOnTaskPostInternal side by side. It implements a single outcome publisher that wraps the ClaimResponse in a Task bundle and posts to the public /v1/task/on_submit path unless configured for the internal one. When a hospital's cancellation Task for an unused preauth is processed, the publisher posts the Task bundle with PC02 semantics under the preauth's correlation id; the hospital acknowledges within 30 seconds and raises a fresh preauth with a new case number for the revised treatment.

### Specification

Chapter [Cancel, reprocess and shortfall](/docs/nhcx/v1/reference/fhir/cancel-reprocess-and-shortfall) of the NHCX integration specification.

Authorizations

Authorizationbearer tokenRequired

On every NHCX call, the token goes in a header called bearer_auth, with the word Bearer and a space in front. The sources are not unanimous: the authentication page and the FAQ both write the example as Authorization, and the notification endpoint uses Authorization. The safe course, and what the adapter does, is to send both headers with the same value.

Headers

bearer_authstringRequired

It is bearer_auth, not Authorization, on NHCX's own endpoints.

x-hcx-sender_codestringRequired

Your participant code. Mandatory on the envelope.

x-hcx-recipient_codestringRequired

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

x-hcx-api_call_idstringRequired

Fresh on every message, including responses. Mandatory on the envelope.

x-hcx-request_idstring

One per originating request. The Open Protocol page marks it Mandatory; the Technical Specifications page marks it Optional. Optional on the envelope.

x-hcx-correlation_idstringRequired

The thread. See the rule below. Mandatory on the envelope.

x-hcx-workflow_idstring

Which step, or which case. See the two readings below. Optional on the envelope.

x-hcx-timestampstringRequired

See the format note below. Mandatory on the envelope.

x-hcx-statusstringRequired

Where this message stands. Values below. Mandatory on the envelope.

x-hcx-ben-abha-idstringRequired

The beneficiary's ABHA number. Mandatory on every exchange, including those with no beneficiary in the payload. Mandatory on the envelope.

Body

payloadstring

Responses

200

Returns 202 Accepted with the StatusSuccessResponse envelope, or 400, 404 or 500 in the same shape; the bundle is forwarded to the provider, which acknowledges within 30 seconds, extracts the ClaimResponse from Task.output and closes the appeal branch.