Guides
  1. Guides
  2. Clinical Alerts

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

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. Notifications are typically delivered in 4 to 24 hours.