Architecture and Behavior

Asynchronous processing is a core part of Health Gorilla’s FHIR R4 architecture. It enables reliable, large-scale data exchange across national networks by processing long-running or high-volume operations in the background.

Health Gorilla’s network aggregation model depends on distributed transactions with external partners such as Carequality, CommonWell, and eHealth Exchange. These systems respond at varying speeds and often return large payloads, making synchronous processing impractical. By queuing requests for background execution, the platform can normalize, consolidate, and deliver complete results without timing out client connections.

Benefits include:

• Reliability: Prevents client and gateway timeouts
• Scalability: Distributes workloads efficiently across systems
• Consistency: Ensures normalized, complete responses from multiple sources
• Performance: Reduces client overhead while results are prepared

Asynchronous handling is not optional; rather, it is the foundation of all R4-based integrations within the Health Gorilla platform.

How Asynchronous Processing Works

When you submit a request with the following header, Health Gorilla processes it asynchronously.

Prefer: respond-async

The server immediately returns a 202 Accepted response containing a Location header that references the pending result.

The final result can then be obtained in one of two ways:

• Webhooks (recommended): Receive a FHIR Subscription notification when processing is complete
• Polling: Query the provided URL periodically until processing is complete

Example Request

GET /fhir/Patient/65e4a45c3c266fc4e5d45c72/$cq-search HTTP/1.1
Host: api.healthgorilla.com
Authorization: Bearer {access_token}
Prefer: respond-async

Example Response

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

Webhook Notification Setup

To receive notifications automatically when an asynchronous request completes, configure a standard FHIR subscription that listens for completed results. Webhook delivery is the preferred production model because it eliminates polling and reduces system overhead.

Health Gorilla’s webhook implementation uses standard FHIR subscriptions for async completion notifications. This replaces the older OperationOutcome?async=true polling pattern, which returned results through a dedicated endpoint. The Subscription approach provides the same functionality using modern FHIR R4 conventions.

Example Subscription Request

{
  "resourceType": "Subscription",
  "status": "active",
  "criteria": "*",
  "channel": {
    "type": "rest-hook",
    "endpoint": "https://your-webhook-url",
    "payload": "application/fhir+json"
  }
}

Example Notification Message

  {
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "id": "p360_d6fd136614df48c6bb11305d",
      "details": { "text": "New resource created" },
      "expression": ["/fhir/R4/RequestResult/p360_d6fd136614df48c6bb11305d"]
    }
  ]
}

Polling for Results

If webhook delivery is not available, you can poll the URL provided in the initial 202 Accepted response to check whether processing is complete or to retrieve the final results.

GET /fhir/RequestResult/3ce13b5ecb4d6633826caca0 HTTP/1.1
Host: api.healthgorilla.com
Authorization: Bearer {access_token}

Polling can be useful during development or in environments that do not yet support webhook endpoints, but it is less efficient and should be used only as a fallback.

RequestResult Behavior

Each asynchronous request includes a Location header that points to a /RequestResult/{id} resource. You can poll this endpoint or receive a webhook notification to retrieve the final result once processing is complete.

The /RequestResult/{id} endpoint returns:

• 202 Accepted: Request is processing
• 200 OK: Result is complete and available
• 454 Expired or Not Found: Result has expired (typically after one hour)
• Other codes: HTTP statuses such as 403 Forbidden or 500 Internal Server Error

This behavior ensures consistent error semantics and simplifies client-side handling.

Response Codes

Always store and log the X-Hg-Request-Id value from the initial 202 Accepted response for debugging and audit traceability.

Best Practices

• Prefer webhooks for completion notifications; use polling only when necessary.
• Secure endpoints with HTTPS, authentication, and sender validation.
• Correlate jobs by logging X-Hg-Request-Id and RequestResult URLs.
• Retrieve results promptly—/RequestResult/{id} expires after about one hour.
• Apply backoff when polling and honor any Retry-After headers.
• Fetch final results from /RequestResult/{id}; webhook payloads are only references.