Migrating to Asynchronous Calls

Most Health Gorilla integrations now use FHIR R4 with asynchronous request processing as the standard model for retrieving clinical data.

Legacy STU3 implementations that rely on synchronous request handling will soon need to migrate to the R4 asynchronous framework to maintain support and benefit from improved reliability and scalability.

This migration ensures full compatibility with the R4 API, eliminates timeouts during long-running or multi-network queries, and aligns your integration with Health Gorilla’s modern architecture for high-performance, distributed workloads.

Migration Steps

Migrating from synchronous to asynchronous processing requires minimal development effort but delivers major performance and reliability gains. The process primarily involves updating request headers and response handling, though most legacy integrations will also update their base URLs to the FHIR R4 API as part of this transition.

This migration does not require major architectural changes—your existing authentication, payload structures, and resource logic remain valid. Once complete, your integration will align with Health Gorilla’s current production model for asynchronous, multi-network data retrieval and delivery.

Add the Async Preference Header

Include the following header in your request to enable asynchronous processing. This instructs the server to queue the job and immediately return a 202 Accepted response instead of waiting for completion.

Prefer: respond-async

Example (Synchronous):

GET /fhir/STU3/Patient/12345
Authorization: Bearer {access_token}
Accept: application/fhir+json

Example (Asynchronous):

GET /fhir/R4/Patient/12345
Authorization: Bearer {access_token}
Accept: application/fhir+json
Prefer: respond-async

The Prefer: respond-async header directs the API to process the request in the background, allowing the connection to close immediately.

Handle the 202 Accepted Response

When the request is accepted, the server responds immediately with a job reference:

HTTP/1.1 202 Accepted
Location: /fhir/RequestResult/3ce13b5ecb4d6633826caca0
X-Hg-Request-Id: 15e2305e94845d4d2f3f7796

Notes:

Location header points to the pending result.
X-Hg-Request-Id should be logged for correlation, auditing, and troubleshooting.

Configure a Completion Method

Choose how your system retrieve the completed results:

Webhook notification (recommended): Register a FHIR Subscription to receive a notification when processing is complete. The notification includes an OperationOutcome with a reference to the completed RequestResult.
Polling (fallback): If webhooks are unavailable, poll the Location URL periodically until the job returns a 200 OK status.

Webhook delivery is recommended in production to minimize load and ensure prompt completion notifications.

Retrieve the Final Result

When notified (via webhook) or when polling indicates completion, call the same /RequestResult/{id} URL to download the final response. The returned resource and HTTP status code are identical to what the synchronous request would have produced.

Summary

Migrating to asynchronous processing involves only small configuration changes but enables scalable, reliable data exchange across Health Gorilla’s connected networks. By updating your integration to FHIR R4 and adopting asynchronous request handling, you ensure long-term compatibility and operational stability across all Health Gorilla services.