The FHIR STU3 Subscription resource allows you to be notified about modifications of Health Gorilla resources in a most convenient way. Active Subscription will be called by Health Gorilla when corresponding resource matching the Subscription criteria has been modified. If call to a Subscription failed then we will try again in 15 minutes. We will keep trying to successfully call Subscription's endpoint with 15 minutes intervals.

Subscription will be disabled and we will not try to call it again until you reenable it if one of the following is true:

Last successful Subscription call is 3 days or older and Subscription calls failed more than 10 times
There are no successful Subscription calls and Subscription calls failed more than 20 times

You can use Subscription endpoint to create and manage subscriptions.

🚧
Subscription Limit
Health Gorilla allows 30 active subscriptions by default. This limit can be increased if needed. To request a limit increase, please contact customer support. Going over the limit will return a 422 response code and an error message.

FHIR Resource: Subscription <https://www.hl7.org/fhir/subscription.html>

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

FHIR Operations

The following operations are currently supported:

1. Read

HTTP Request	Method	Action
/Subscription/`{ID}`	GET	Get Subscription by ID

2. Search

HTTP Request	Method	Action
/Subscription?[parameter=`{value}`]	GET

Parameters:

Key	Type	Description
status	Token	The current state of the subscription (active, requested, error, off)
type	Token	The type of channel for the sent notifications

3. Delete

HTTP Request	Method	Action
/Subscription	DELETE	Deletes subscription

4. Create

HTTP Request	Method	Action
/Subscription	POST	Creates new subscription

Limited number of resources is supported, while some resources support filters that you can use in criteria:

Resource	Additional attributes you can use in criteria	Payload
DiagnosticReport	_ patient _ category * status
DocumentReference	_ patient _ class * type
DocumentReference.OCR		application/hg-ocr+json
RequestGroup	* patient
ProcedureRequest	* patient
FaxMessage	_ direction _ deliveryFailed
DirectMessage	* direction
Patient	_ gender _ birthDate [eq, gt, lt] * postalCode
Patient.P360		application/hg-event+json
Condition	* patient
Consent	* patient
AllergyIntolerance	* patient
Immunization	* patient
MedicationRequest	* patient
MedicationStatement	* patient
MedicationDispense	* patient
NutritionOrder	* patient
Encounter	* patient
CarePlan	* patient
DeviceUseStatement	* patient
Observation	* patient, category
FamilyMemberHistory	* patient
Goal	* patient
Procedure	* patient
Coverage	* patient (required)	none

Examples

4.1 Retrieve Subscriptions by type:

https://api.healthgorilla.com/fhir/Subscription
?type=http://hl7.org/fhir/subscription-channel-type|rest-hook

4.2 Create new subscription for DiagnosticReport resource updates:

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

Headers: Content-Type: application/json

{
  "resourceType": "Subscription",
  "status": "active",
  "end": "2021-01-01T00:00:00Z",
  "reason": "Monitor new neonatal function",
  "criteria": "DiagnosticReport",
  "channel": {
    "type": "rest-hook",
    "endpoint": "https://myservice.com/healthgorilla/webhook",
    "payload": "application/fhir+json",
    "header": [
      "Authorization: Bearer secret-token-abc-123"
    ]
  }
}

4.3 Create new subscription for failed outgoing FaxMessage resources.

This subscription will be called when Health Gorilla can not deliver electronic fax to the recipient. See FaxResource for more information.

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

Headers: Content-Type: application/json

{
    "resourceType": "Subscription",
    "status": "active",
    "end": "2020-01-01T00:00:00Z",
    "reason": "Dev",
    "criteria": "FaxMessage?direction=OUT&deliveryFailed=true",
    "channel": {
        "type": "rest-hook",
        "endpoint": "https://myservice.com/healthgorilla/webhook",
        "payload": "application/hg-event+json",
        "header": [
            "Authorization: Bearer secret-token-hg"
        ]
    }
}

4.4 Create new subscription with the REST hook signing secret

Health Gorilla can sign payload of your Subscription calls with HMAC-SHA Signature. Below is an example how can you specify signature's secret to be used. Note that you can not read the secret back. Endpoint returns only key id and expiration date.

{
    "resourceType": "Subscription",
    "status": "active",
    "end": "2022-01-01T00:00:00Z",
    "reason": "Testing",
    "criteria": "Patient",
    "channel": {
        "type": "rest-hook",
        "endpoint": "https://qaadmin.healthgorilla.com/extsub/webhook",
        "payload": "application/hg-ocr+json",
        "header": [
            "Authorization: Bearer accc5e72ac51fc53c6881b9a5d122765"
        ],
        "extension": [
            {
                "url": "https://www.healthgorilla.com/fhir/StructureDefinition/subscription-channelSecret",
                "extension": [
                    {
                        "url": "value",
                        "valueString": "my-signing-key"
                    },
                    {
                        "url": "id",
                        "valueString": "key-1"
                    },
                    {
                        "url": "end",
                        "valueDateTime": "2022-02-02T02:02:02+03:00"
                    }
                ]
            }
        ]
    }
}

Notification request payload headers and signature will be constructed as follows:

Header Name	Definition
Date	day-name, day month year hour:minute:second GMT
Digest	SHA-512 checksum of the payload
X-Hg-EventId	The ID of the event
X-Hg-EventCreated	When the event was issued
X-Hg-Signature	HMAC with the SHA512 hash function

In order to verify signature Subscription responder should:

Read Date, X-Hg-EventId and X-Hg-Signature headers of the request
Construct StringToSign value like:

StringToSign = <Date> + "\n" +
               <X-Hg-EventId> + "\n" +
               <Digest>

Calculate the expected signature by computing HMAC with the SHA512 hash function and then adding 'sha512=' as a prefix
Compare the signature in the request header <X-Hg-Signature> to the calculated expected signature

4.5 Create a Subscription with Oauth 2.0 Client Credentials

Health Gorilla offers users the capability to create a secure subscription for protecting their webhooks by utilizing the OAuth 2.0 client credential flow. This feature ensures that any data transmitted to the user's webhook is safeguarded with an additional layer of security, requiring proper authentication through OAuth 2.0.

🚧
The Oauth credentials for the subscription should be the Oauth credentials created by the user and NOT the Oauth credentials provided by Health Gorilla to access our APIs.

Attribute Name (valueString)	Required	Description
client_id	Y	The Oauth client ID assigned to Health Gorilla by the user
client_secret	Y	The Client Secret assigned to Health Gorilla by the user
scope	N	The scope required (if any) to allow Health Gorilla to send the notifications to the webhook
oauth_endpoint_url	Y	The URL that will be used by Health Gorilla to authenticate.
headerName:headerValue	N	Any header that might be required by the user's webhook. Can be multiple.

{
    "resourceType": "Subscription",
    "status": "active",
    "end": "2023-09-09T00:00:00Z",
    "reason": "Test Comprehend Medical",
    "criteria": "Patient",
    "channel": {
        "type": "rest-hook",
        "endpoint": "https://yourwebhook.com",
        "payload": "application/fhir+json",
        "header": [
            "<headerName>: <headerField>"
        ],
        "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": "<CLIENT_ID>"
                    },
                    {
                        "url": "clientSecret",
                        "valueString": "<CLIENT_SECRET>"
                    },
                    {
                        "url":"scope",
                        "valueString":"<SCOPE>"
                    },
                    {
                        "url":"endpoint",
                        "valueUri": "<OAUTH_ENDPOINT_URL>"
                    },
                    {
                        "url":"header",
                        "valueString": "<headerName>: <headerValue>"
                    }
                ]
    }]
}
}

5. Update

5.1 Update Subscription.channel.header

The subscription endpoint supports the FHIR Patch operation and accepts a JSON Patch payload.

Path	Operations
/channel/header	- add - replace - remove

PATCH /fhir/Subscription/1e2d645b16673dd785f371d8 HTTP/1.1
Host: api.healthgorilla.com
Content-Type: application/json-patch+json
{
    "op": "add",
    "path": "/channel/header",
    "value": [
        "X-WebHook-Key: my-key",
        "Authorization: Bearer accc5e72ac51fc53c6881b9a5d122765"
    ]
}

5.1 Update Signing Secret

Operation: FHIR PATCH Format: Json PATCH Operations: add/replace/remove

PATCH /fhir/Subscription/1e2d645b16673dd785f371d8 HTTP/1.1
Host: api.healthgorilla.com
Content-Type: application/json-patch+json
{
    "op": "add",
    "path": "/channel/secret",
    "value": {
        "value" : "my-key",
        "id" : "hmac-256-1",
        "end" : "2022-02-02T02:02:02"
    }
}

5.2 Update Oauth Credentials

Operation: FHIR PATCH

Format: JSON Patch

Operations: replace

PATCH /fhir/Subscription/1e2d645b16673dd785f371d8 HTTP/1.1
Host: api.healthgorilla.com
Content-Type: application/json-patch+json
{
    "op": "replace",
    "path": "/channel/oauth",
    "value": {
        "grantType" : "client_credentials",
        "clientId" : "<CLIENT_ID>",
        "clientSecret" : "<CLIENT_SECRET>",
        "scope" : "<SCOPE>",
        "endpoint" : "<OAUTH_ENDPOINT_URL>"
    }
}

Subscription channel types

Health Gorilla supports rest-hook and web socket channels from the list <https://www.hl7.org/fhir/valueset-subscription-channel-type.html>

Rest hook

You can receive callback to the specified endpoint. And this is a highly recommended to add HTTP headers to the channel, that you will use to authorize the callback. Only endpoints that use TLS1.2+ can be accepted.

Supported payloads:

Payload	Description
No payload	See https://www.hl7.org/fhir/subscription.html#2.46.6.1 for details
application/fhir+xml	See https://www.hl7.org/fhir/subscription.html#2.46.6.1 for details
application/fhir+json	See https://www.hl7.org/fhir/subscription.html#2.46.6.1 for details
application/hg-event+json	Health Gorilla sends simple JSON event to client's endpoint with the resource type and resource’s identifier that triggered the event. For example: { “resource” : "RequestGroup", “id” : "RequestGroup/d6fjlvj9gjb9djlaww8q" }
application/hg-ocr+json	{ "resource":"DocumentReference", "id":"7e00155db23e480d67609b59", "ocr":[ { "name":"laboratory_result.pdf", "contentType":"application/pdf", "success":true, "entities":[ { "resource":"Entity", "id":0, "category":"PROTECTED_HEALTH_INFORMATION", "type":"DATE", "text":"Mon 05 Nov 2012", "score":0.99408334 }, { "resource":"Entity", "id":52, "category":"MEDICAL_CONDITION", "type":"DX_NAME", "text":"venous thrombosis", "score":0.9674222, "traits":[ { "resource":"Trait", "name":"DIAGNOSIS", "score":0.9529462 } ] }, ... ] } ] }

If you use no-payload mode, then you can query Health Gorilla FHIR server for the list of recently modified resources by appending “&_lastUpdated=<date>” parameter to the search criteria.

Web Socket

You can connect to secure Web Socket and receive runtime notifications.

To do so you need to use OAuth access token to authorize connection.

Web Socket endpoint is defined in the server's CapabilityStatement. See <https://www.hl7.org/fhir/extension-capabilitystatement-websocket.html> for more information

Example

Subscribe for new MedicationRequest received for the given patient.

{
  "resourceType": "Subscription",
  "status": "active",
  "end": "2022-01-01T00:00:00Z",
  "reason": "Monitor activity",
  "criteria": "MedicationRequest?patient=03db4352ee0190ad5e9e6748",
  "channel": {
    "type": "rest-hook",
    "endpoint": "https://myservice.com/healthgorilla/webhook",
    "payload": "application/hg-event+json",
    "header": [
      "Authorization: Bearer my-secret-token"
    ]
  }
}

ADT Message Subscription

ADT messages contain important updates to patient demographic information and their clinical "status", e.g. admissions, discharges, and transfers, which can be important for patient care management.

You can be notified when new ADT Message is received in your account.

Create a new subscription:

Property	Value
Subscription.channel.type	messaging
Subscription.channel.endpoint	Include operation $process-message
Subscription.channel.payload	application/fhir+json

{
    "resourceType": "Subscription",
    "status": "active",
    "end": "2022-01-01T00:00:00Z",
    "reason": "ADT events",
    "criteria": "Bundle?message.event=admin-notify",
    "channel": {
        "type": "message",
        "endpoint": "https:/fhir.mycompany.com/extsub/webhook/$process-message",
        "payload": "application/fhir+json"
    }
}

Read ADT events

Read ADT events created since the specified date:

Parameter	Type	Details	Required
message.event	token	admin-notify	Yes
message.focus	reference	patient logical ID	No
_lastUpdated	date		No
_offset	number	Default: 0	No
_count	number	Default: 100	No
eventType	string	One of codes A01 - A62	No

{{portalUrl}}/fhir/Bundle?message.event=admin-notify&_lastUpdated=2021

Example: read ADT event by ID

{{portalUrl}}/fhir/Bundle?message._id=234b056061f93146a983072f

{
    "resourceType": "Bundle",
    "id": "0ef188e4-e0ab-4006-b354-6bd78f62eda4",
    "meta": {
        "lastUpdated": "2021-07-09T20:52:15.434+00:00"
    },
    "type": "searchset",
    "total": 1,
    "link": [
        {
            "relation": "self",
            "url": "https://api.healthgorilla.com/fhir/Bundle?message._id=234b056061f93146a983072f"
        }
    ],
    "entry": [
        {
            "fullUrl": "https://api.healthgorilla.com/fhir/Bundle/91fdeae7-12ac-4c0f-8886-fa1d9e8de2e0",
            "resource": {
                "resourceType": "Bundle",
                "id": "91fdeae7-12ac-4c0f-8886-fa1d9e8de2e0",
                "type": "message",
                "entry": [
                    {
                        "fullUrl": "urn:uuid:234b056061f93146a983072f",
                        "resource": {
                            "resourceType": "MessageHeader",
                            "id": "09c71b60ec62c22dc09267ac",
                            "contained": [
                                {
                                    "resourceType": "Organization",
                                    "id": "1",
                                    "name": "GOOD HEALTH HOSPITAL"
                                }
                            ],
                            "event": {
                                "system": "http://hl7.org/fhir/message-events",
                                "code": "admin-notify",
                                "display": "admin-notify"
                            },
                            "sender": {
                                "reference": "#1"
                            },
                            "timestamp": "1988-08-18T11:26:00+00:00",
                            "source": {
                                "name": "ADT1",
                                "software": "ADT1"
                            },
                            "focus": [
                                {
                                    "reference": "Patient/09c71b60b4b8d62360f1b8f6",
                                    "display": "ADAM A EVERYMAN"
                                }
                            ]
                        }
                    },
                    {
                        "fullUrl": "urn:uuid:patient",
                        "resource": {
                            "resourceType": "Patient",
                            "id": "patient",
                            "meta": {
                                "versionId": "1612433161124",
                                "lastUpdated": "2021-02-04T10:06:01.124+00:00",
                                "profile": [
                                    "http://hl7.org/fhir/us/core/StructureDefinition/us-core-patient",
                                    "http://fhir.org/guides/argonaut/StructureDefinition/argo-patient"
                                ]
                            },
                            "text": {
                                "status": "generated",
                                "div": "<div xmlns=\"http://www.w3.org/1999/xhtml\">ADAM A EVERYMAN, 60y.o., Male, GREENSBORO, NC, United States</div>"
                            },
                            "identifier": [
                                {
                                    "use": "usual",
                                    "type": {
                                        "coding": [
                                            {
                                                "system": "http://hl7.org/fhir/v2/0203",
                                                "code": "MR",
                                                "display": "Medical record number"
                                            }
                                        ],
                                        "text": "Medical record number"
                                    },
                                    "system": "https://www.healthgorilla.com",
                                    "value": "09c71b60b4b8d62360f1b8f6"
                                },
                                {
                                    "type": {
                                        "coding": [
                                            {
                                                "system": "http://hl7.org/fhir/identifier-type",
                                                "code": "SB",
                                                "display": "Social Beneficiary Identifier"
                                            }
                                        ],
                                        "text": "Social Beneficiary Identifier"
                                    },
                                    "system": "http://hl7.org/fhir/sid/us-ssn",
                                    "value": "444333333"
                                },
                                {
                                    "type": {
                                        "coding": [
                                            {
                                                "system": "http://hl7.org/fhir/v2/0203",
                                                "code": "MR",
                                                "display": "Medical record number"
                                            }
                                        ],
                                        "text": "Medical record number"
                                    },
                                    "value": "391141"
                                }
                            ],
                            "active": true,
                            "name": [
                                {
                                    "text": "ADAM A EVERYMAN",
                                    "family": "EVERYMAN",
                                    "given": [
                                        "ADAM",
                                        "A"
                                    ]
                                }
                            ],
                            "telecom": [
                                {
                                    "system": "phone",
                                    "value": "(555) 555-2004",
                                    "use": "home"
                                },
                                {
                                    "system": "phone",
                                    "value": "(555) 555-2004",
                                    "use": "work"
                                }
                            ],
                            "gender": "male",
                            "birthDate": "1961-06-15",
                            "address": [
                                {
                                    "text": "2222 HOME STREET, GREENSBORO, NC 27401",
                                    "line": [
                                        "2222 HOME STREET"
                                    ],
                                    "city": "GREENSBORO",
                                    "state": "NC",
                                    "postalCode": "27401-1020",
                                    "country": "USA"
                                }
                            ],
                            "maritalStatus": {
                                "coding": [
                                    {
                                        "system": "http://hl7.org/fhir/v3/MaritalStatus",
                                        "code": "U",
                                        "display": "Unmarried"
                                    }
                                ],
                                "text": "Single"
                            },
                            "link": [
                                {
                                    "other": {
                                        "reference": "Patient/09c71b60b4b8d62360f1b8f6",
                                        "display": "ADAM A EVERYMAN"
                                    },
                                    "type": "refer"
                                }
                            ]
                        }
                    },
                    {
                        "fullUrl": "urn:uuid:enc",
                        "resource": {
                            "resourceType": "Encounter",
                            "id": "enc",
                            "contained": [
                                {
                                    "resourceType": "Practitioner",
                                    "id": "1",
                                    "identifier": [
                                        {
                                            "value": "004777"
                                        }
                                    ],
                                    "name": [
                                        {
                                            "text": "AARON A ATTEND",
                                            "family": "ATTEND",
                                            "given": [
                                                "AARON",
                                                "A"
                                            ]
                                        }
                                    ]
                                },
                                {
                                    "resourceType": "Location",
                                    "id": "2",
                                    "name": "01",
                                    "physicalType": {
                                        "coding": [
                                            {
                                                "system": "http://hl7.org/fhir/location-physical-type",
                                                "code": "bd",
                                                "display": "Bed"
                                            }
                                        ],
                                        "text": "Bed"
                                    },
                                    "partOf": {
                                        "reference": "#3"
                                    }
                                },
                                {
                                    "resourceType": "Location",
                                    "id": "3",
                                    "name": "2012",
                                    "physicalType": {
                                        "coding": [
                                            {
                                                "system": "http://hl7.org/fhir/location-physical-type",
                                                "code": "ro",
                                                "display": "Room"
                                            }
                                        ],
                                        "text": "Room"
                                    },
                                    "partOf": {
                                        "reference": "#4"
                                    }
                                },
                                {
                                    "resourceType": "Location",
                                    "id": "4",
                                    "name": "2000"
                                }
                            ],
                            "class": {
                                "system": "http://terminology.hl7.org/CodeSystem/v2-0004",
                                "code": "I",
                                "display": "Inpatient"
                            },
                            "subject": {
                                "reference": "Patient/patient"
                            },
                            "participant": [
                                {
                                    "type": [
                                        {
                                            "coding": [
                                                {
                                                    "system": "http://hl7.org/fhir/v3/ParticipationType",
                                                    "code": "ATND",
                                                    "display": "Attender"
                                                }
                                            ]
                                        }
                                    ],
                                    "individual": {
                                        "reference": "#1"
                                    }
                                }
                            ],
                            "location": [
                                {
                                    "location": {
                                        "reference": "#2"
                                    }
                                }
                            ]
                        }
                    }
                ]
            }
        }
    ]
}

Patient360 Subscription

You can be notified when a batch of CDA documents is imported from the data exchange networks. Patient360 Subscription will be triggered in the following scenarios:

Documents for the patient are queried and retrieved via Patient360 UI
Single document is imported for the patient
Batch of documents is imported for the patient

Create a new subscription:

Property	Value
Subscription.criteria	Patient.P360
Subscription.channel.payload	application/hg-event+json

{
    "resourceType": "Subscription",
    "status": "active",
    "end": "2022-01-01T00:00:00Z",
    "reason": "Patient360",
    "criteria": "Patient.P360",
    "channel": {
        "type": "rest-hook",
        "endpoint": "https://mysyte.com/healthgorilla/callback",
        "payload": "application/hg-event+json",
        "header": [
            "X-Hg-Callback-Key: accc5e72ac51fc53c6881b9a5d122765=="
        ]
    }
}

If CDA documents have been imported, HealthGorilla makes a webhook call and provides the reference to the patient.

POST /healthgorilla/callback HTTP/1.1
Host: mysyte.com/healthgorilla
X-Hg-Callback-Key: accc5e72ac51fc53c6881b9a5d122765==
Content-Type: application/json
{
    “resource” : "Patient",
    “id” : "Patient/e9b7c05fb9c6de7fb3abb4b1"
}