Subscribing to Events

Health Gorilla supports FHIR R4 Subscription resources for event-driven notifications. Subscriptions allow your application to receive webhook notifications when supported resource events occur, reducing the need for polling.

Health Gorilla delivers notifications to your configured endpoint when a resource matching the subscription criteria is created or updated.

Endpoint URI

Use the FHIR R4 endpoint for subscription management:

https://api.healthgorilla.com/fhir/R4/Subscription

Subscription Behavior

Active subscriptions trigger outbound notifications when matching events occur. If a notification attempt fails, Health Gorilla retries delivery every 15 minutes. Retries continue at 15-minute intervals until delivery succeeds or the subscription is disabled.

A subscription is disabled when either of the following conditions is met:

• The last successful delivery is 3 days old or older and delivery has failed more than 10 times
• No successful delivery has occurred and delivery has failed more than 20 times

Once disabled, the subscription must be re-enabled before notifications resume.

Subscription Limits

Health Gorilla allows 30 active subscriptions by default. This limit can be increased upon request.

Requests that exceed the active subscription limit return:

• 422 Unprocessable Entity

Supported Operations

Subscriptions can be created, retrieved, updated, searched, and deleted using standard FHIR operations.

Create

POST /fhir/R4/Subscription
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/fhir+json

Read

GET /fhir/R4/Subscription/{id}
Authorization: Bearer YOUR_ACCESS_TOKEN
Accept: application/fhir+json

Search

GET /fhir/R4/Subscription?status=active
Authorization: Bearer YOUR_ACCESS_TOKEN
Accept: application/fhir+json

Supported search parameters:

• status: Requested, active, error, off
• type: Subscription channel type

Delete

DELETE /fhir/R4/Subscription/{id}
Authorization: Bearer YOUR_ACCESS_TOKEN

Update

Health Gorilla supports FHIR Patch for selected subscription updates.

Creating a Subscription

The following example creates a subscription for DiagnosticReport updates.

{
  "resourceType": "Subscription",
  "status": "active",
  "end": "2027-01-01T00:00:00Z",
  "reason": "Monitor diagnostic report updates",
  "criteria": "DiagnosticReport",
  "channel": {
    "type": "rest-hook",
    "endpoint": "https://yourapp.com/webhooks/hg",
    "payload": "application/fhir+json",
    "header": [
      "Authorization: Bearer YOUR_WEBHOOK_TOKEN"
    ]
  }
}

Supported Criteria

The criteria field defines which resource events trigger notifications. Health Gorilla supports criteria based on resource type and selected attributes.

Examples:

Contact your Health Gorilla integration team to define criteria aligned with your workflow.

Supported Resources

Health Gorilla supports subscriptions for selected FHIR resources. Availability may vary based on configuration.

• DiagnosticReport
• DocumentReference
• Condition
• AllergyIntolerance
• Immunization
• MedicationRequest
• MedicationStatement
• Observation
• Encounter
• CarePlan
• Goal
• Procedure
• Coverage

Additional resources and criteria may be available depending on your configuration.

Channel Types

Health Gorilla supports the following subscription channel types:

• rest-hook
• websocket

REST Hook

REST hook delivers notifications to an HTTPS endpoint.

Requirements:

• Endpoints must use HTTPS
• TLS 1.2 or higher is required

Supported payload types:

• application/fhir+json
• application/hg-event+json
• application/hg-ocr+json
• No payload

Example Event Payload (application/hg-event+json)

{
  "resource": "RequestGroup",
  "id": "RequestGroup/d6fjlvj9gjb9djlaww8q"
}

If no payload is used, retrieve updates using the _lastUpdated parameter in search queries.

WebSocket

WebSocket connections support event-driven notifications over a persistent connection.

• Requires OAuth 2.0 access token for authorization
• Endpoint is defined in the FHIR CapabilityStatement

Signing and Security

Health Gorilla can sign webhook payloads using HMAC-SHA512.

Notification headers include:

• Date
• Digest
• X-Hg-EventId
• X-Hg-EventCreated
• X-Hg-Signature

To verify the signature:

1. Read the Date, X-Hg-EventId, Digest, and X-Hg-Signature headers.
2. Construct the string to sign:

<Date>\n
<X-Hg-EventId>\n
<Digest>

WebSocket

WebSocket connections support event-driven notifications over a persistent connection.

• Requires OAuth 2.0 access token for authorization
• Endpoint is defined in the FHIR CapabilityStatement

Signing and Security

Health Gorilla can sign webhook payloads using HMAC-SHA512.

Notification headers include:

• Date
• Digest
• X-Hg-EventId
• X-Hg-EventCreated
• X-Hg-Signature

To verify the signature:

1. Read the Date, X-Hg-EventId, Digest, and X-Hg-Signature headers.
2. Construct the string to sign:

<Date>\n
<X-Hg-EventId>\n
<Digest>

3. Compute the expected HMAC using SHA-512 and the configured signing secret.
4. Prefix the computed value with sha512=.
5. Compare the computed value to the X-Hg-Signature header.

OAuth 2.0 for Webhooks

Health Gorilla supports OAuth 2.0 client credentials flow for securing webhook delivery.

The OAuth credentials used for webhook authentication must be issued by your organization. Do not use the OAuth credentials provided by Health Gorilla for API access.

Required attributes:

• clientId
• clientSecret
• endpoint

Optional attributes:

• scope
• additional headers

Example: Subscription with OAuth 2.0 Client Credentials

{
  "resourceType": "Subscription",
  "status": "active",
  "end": "2027-09-09T00:00:00Z",
  "reason": "OAuth protected webhook",
  "criteria": "Patient",
  "channel": {
    "type": "rest-hook",
    "endpoint": "https://yourwebhook.com",
    "payload": "application/fhir+json",
    "header": [
      "X-Custom-Header: VALUE"
    ],
    "extension": [
      {
        "url": "https://www.healthgorilla.com/fhir/StructureDefinition/subscription-channelRestHookOAuth",
        "extension": [
          {
            "url": "grantType",
            "valueCoding": {
              "system": "https://www.healthgorilla.com/oauth-grant-type",
              "code": "client-credentials",
              "display": "Client Credentials"
            }
          },
          {
            "url": "clientId",
            "valueString": "YOUR_CLIENT_ID"
          },
          {
            "url": "clientSecret",
            "valueString": "YOUR_CLIENT_SECRET"
          },
          {
            "url": "scope",
            "valueString": "YOUR_SCOPE"
          },
          {
            "url": "endpoint",
            "valueUri": "https://your-auth-server.com/oauth/token"
          },
          {
            "url": "header",
            "valueString": "X-Header: VALUE"
          }
        ]
      }
    ]
  }
}

ADT Event Subscriptions

Subscriptions can be configured for ADT (admission, discharge, transfer) event notifications.

Example criteria:

Bundle?message.event=admin-notify

Supported search parameters:

Patient360 Subscriptions

Subscriptions can notify your system when new documents are imported for a patient.

• Supported scenarios include:
• Documents retrieved through Patient360 workflows
• Single document import for a patient
• Batch document import for a patient

Example criteria:

Patient.P360

Example Notification

POST /healthgorilla/callback HTTP/1.1
Host: yoursystem.com
Content-Type: application/json

{
  "resource": "Patient",
  "id": "Patient/e9b7c05fb9c6de7fb3abb4b1"
}