Event-Driven Subscriptions

Event-driven subscriptions are the primary and recommended model for data delivery. You register a subscription that defines the scope of data to monitor, such as resource types, codes, or a patient roster. When qualifying data is detected, Health Gorilla sends a notification to your configured endpoint. Event-driven subscriptions minimize latency, eliminate manual polling, and ensure connected systems remain synchronized with current clinical information.

Delivery Methods

FHIR Subscriptions (Preferred)

FHIR subscriptions are the standard and preferred delivery method. Notifications are delivered to your HTTPS endpoint when events occur. Each message is digitally signed for integrity, and delivery is retried automatically using exponential backoff if your endpoint is temporarily unavailable.

Requirements

• Provide a publicly accessible HTTPS endpoint secured with TLS
• Accept signed requests and verify the signature header
• Respond immediately with a 2xx status code; perform downstream processing asynchronously to prevent timeouts

Notification Contents

• Subscription identifier and event type
• References to new or updated FHIR resources
• URLs that can be followed to retrieve complete resource content

Examples

• Clinical Alerts deliver notifications for new encounters such as emergency department visits
• Patient360 subscriptions send notifications when new clinical documents are imported from Carequality or CommonWell
• Bulk export jobs issue a notification when processing completes and batch files are available for download

HL7 v2 Messages (Legacy)

For environments that rely on existing HL7 infrastructure, subscriptions can deliver synthetic HL7 v2 messages. This method preserves compatibility with legacy systems while using event-driven logic behind the scenes.

Characteristics

• Compatible with EHR and laboratory interface engines
• Uses standard HL7 v2 ADT and ORU message structures
• Requires an HL7 endpoint configured to receive inbound messages

Examples

• Clinical Alerts delivered as HL7 v2 A08 messages for encounter updates
• Laboratory results delivered as HL7 v2 ORU R01 messages for downstream processing

Polling (Fallback)

Polling is supported as a fallback when inbound webhooks are not possible. Your system creates a subscription but must actively query the server to check for updates.

Considerations

• Adds latency and increases API traffic compared to push delivery
• Appropriate only in environments where subscription-based delivery is not feasible
• Not recommended for production implementations

Non-Subscription Workflows

Some environments rely on scheduled API queries rather than event-driven notifications. While simple to implement, this approach increases overhead and delays the detection of new data. Scheduled queries should be used only when FHIR subscriptions cannot be deployed.

Example Nightly batch jobs that retrieve updated Patient360 records for a predefined roster.

Best Practices

To ensure reliable, secure, and efficient delivery:

• Use FHIR subscriptions for all production implementations
• Keep subscription endpoints lightweight and acknowledge notifications with a 2xx response immediately
• Perform all downstream processing asynchronously after acknowledgment
• Verify message signatures to confirm authenticity and rotate credentials regularly
• Deduplicate notifications using the unique identifier included in each event
• Monitor endpoint availability, latency, and error rates
• Limit subscription scope to relevant patients, resource types, or codes to reduce noise