Create a Subscription

You can create a FHIR subscription to automatically receive notifications when new or updated data meets defined criteria. Each subscription specifies the resource type, filters, and delivery channel used to send notifications from Health Gorilla to your system.

When relevant data is detected—such as new lab results, encounter updates, or imported documents—Health Gorilla delivers a notification to your configured endpoint. Your system acknowledges receipt with a 2xx response and processes the event asynchronously so your organization can respond efficiently to new information.

Define the Subscription

A FHIR subscription resource includes the following key elements.

Element	Description
criteria	Defines the FHIR resource type and any filters that determine when notifications are sent.
channel.type	Specifies how notifications are delivered. Health Gorilla supports secure HTTPS delivery through FHIR subscriptions.
channel.endpoint	The URL of your system’s endpoint that receives notifications.
channel.payload	Defines the format of the notification payload, such as `application/fhir+json` or `application/hg-event+json`.
channel.header	Contains authorization or other HTTP headers required by your system.
status	Indicates whether the subscription is `active`, `off`, or `error`.
end	Optional expiration date for the subscription.

Example: Diagnostic Report Subscription

POST https://api.healthgorilla.com/fhir/Subscription
Content-Type: application/json

{
  "resourceType": "Subscription",
  "status": "active",
  "reason": "Monitor new lab results",
  "criteria": "DiagnosticReport?category=laboratory",
  "channel": {
    "type": "rest-hook",
    "endpoint": "https://your-system.com/healthgorilla/webhook",
    "payload": "application/fhir+json",
    "header": [
      "Authorization: Bearer YOUR_ACCESS_TOKEN"
    ]
  }
}

When a new or updated DiagnosticReport resource meets the defined criteria, Health Gorilla sends a notification to your system’s endpoint. Your system processes the event and retrieves the corresponding FHIR resource as needed.

Best Practices

Define filters precisely to avoid unnecessary notifications
Configure your system to acknowledge each notification immediately
Process notifications asynchronously to prevent timeouts
Rotate authentication credentials regularly
Monitor endpoint performance and review subscription logs for delivery verification