Delivery and Payloads

Clinical Alerts notifications are delivered through one of two configured transport methods. Your organization selects the delivery method that integrates with your downstream systems. Only one delivery method may be configured per tenant.

FHIR Subscription

Health Gorilla sends notifications as HTTP POST requests to your designated HTTPS endpoint. Your system must return a 2xx status code to acknowledge receipt. Non-2xx responses are treated as delivery failures and may result in retry attempts. Retry behavior follows configured delivery policies and does not guarantee eventual delivery.

FHIR Payload Structure

FHIR-based notifications include a Parameters resource that contains an embedded Encounter resource representing inferred clinical activity.

The embedded Encounter provides context such as:

• Encounter class
• Encounter timing
• Patient reference
• Facility or organization context

This encounter represents document-derived activity and should not be treated as an authoritative or complete source-system encounter record.

Example FHIR Payload

{
  "resourceType": "Parameters",
  "parameter": [
    { "name": "eventType", "valueString": "clinical-alert" },
    {
      "name": "encounter",
      "resource": {
        "resourceType": "Encounter",
        "id": "1234567",
        "class": { "code": "IMP" },
        "subject": { "reference": "Patient/98765" }
      }
    }
  ]
}

Secure File Transfer Protocol (SFTP)

Notifications are written as files to your designated SFTP location. Your system retrieves and processes files as part of its normal ingestion workflow.

HL7 v2 A08 Payload

When SFTP delivery is configured, notifications arrive as HL7 v2 A08 messages containing patient and encounter-level details across MSH, PID, and PV1 segments.

Key segments may include:

• MSH: Message header and message control identifier
• PID: Patient identification information
• PV1: Encounter-level details such as class and facility context

Example HL7 v2 A08 Message

MSH|^~\&|HG|HG|CLIENT|CLIENT|202401011200||ADT^A08|123456|P|2.5
PID|1||98765^^^HG||DOE^JANE||19800101|F
PV1|1|I|||^^^St. Mary Hospital||||||||||||1234567

Leading Indicator Payload

A Leading Indicator describes the query rather than a document, so it references no DocumentReference: no document is retrieved at the point a query is observed.

The notification is sent with the content type application/json. Its body borrows the shape of a FHIR Patient for familiarity, but it is a fixed event schema rather than a conformant FHIR resource: it carries flat query fields alongside the standard elements, it holds none of the other elements a Patient normally carries, and validating it against the FHIR schema fails. Treat it as a webhook payload, not as a resource to validate, store, or post to a FHIR endpoint. The id it carries is the matched patient's Health Gorilla identifier, which you can read through the standard FHIR API, but the indicator itself has no FHIR resource behind it and cannot be fetched by id.

The querying organization travels inside the payload as a contained resource, meaning it is embedded inline rather than referenced, so you don't need a second call to look it up. The payload carries these fields.

Fields with no value are omitted rather than sent as null, so read a missing key as no value rather than treating its absence as an error. resourceType and contained are always present. id, network, queryType, purposeOfUse, and timestamp can each be absent. id is the one worth handling deliberately: it carries the matched patient, so an indicator without it can't be tied to a patient. Log and discard rather than treating it as a processing failure. purposeOfUse carries TREATMENT on every indicator, because no other purpose generates one, so build against the value rather than against its presence.

Logging and Traceability

To support deduplication and downstream correlation, your system should log the following identifiers from each notification:

• X-Hg-EventId (HTTP header on FHIR Subscription deliveries)
• Encounter.id (FHIR payloads)
• MSH-10 (HL7 v2 message control ID)
• PID-3 (HL7 v2 patient identifier)

Use these identifiers to recognize and deduplicate repeated deliveries.

Source Document Access

Clinical Alerts provides two paths for accessing the source document associated with an alert. The path available to your organization depends on whether your tenant is licensed for C-CDA storage.

Document Delivery (Optional, Licensed)

For organizations licensed for C-CDA storage, Clinical Alerts imports the source document into the patient's chart as part of alert generation. The document is stored as a FHIR R4 DocumentReference resource, marked with the originating network (for example, carequalityImport, qhinImport), and flagged for exclusion from shareback.

Accessing the Document

Once stored, the document is available through:

• FHIR R4 DocumentReference API on the patient's chart
• Patient Chart UI

Notification for Document Arrival

To be notified when each alert-derived document arrives in the chart, create a DocumentReference subscription with the clinicalAlerts=true filter:

{
  "resourceType": "Subscription",
  "criteria": "DocumentReference?clinicalAlerts=true",
  "channel": {
    "type": "rest-hook",
    "endpoint": "https://your.endpoint/clinical-alert-documents"
  }
}

The filter is backward compatible. Existing DocumentReference subscriptions without the filter are unaffected and continue to receive all matching documents.

Enablement

C-CDA storage is provisioned by Health Gorilla on request. For more information about this feature, contact Health Gorilla.

Patient360 Document Retrieval

For organizations not licensed for C-CDA storage, you can access source documents on demand through standard Patient360 retrieval workflows when an alert indicates activity requiring review. Document availability varies based on network participation and configuration.

Responsibilities

Your organization is responsible for:

• Configuring and maintaining the delivery endpoint
• Acknowledging receipt of notifications
• Implementing idempotent processing using stored identifiers
• Ingesting and downstream processing of notifications

Health Gorilla is responsible for:

• Generating notifications based on detected clinical activity
• Delivering notifications to the configured endpoint
• Importing source documents for organizations licensed for C-CDA storage

Relationship to Other Notifications

FHIR Subscription delivery may also be used for other notification types, including HL7 v2 ADT messages. Clinical Alerts are a separate notification type; receiving ADT notifications does not automatically include Clinical Alerts. Clinical Alerts delivery must be configured independently for your tenant.

Important Limitations

Notification delivery is asynchronous. Alerts are processed and delivered as soon as possible rather than on a fixed schedule.