Subscriptions

The 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 RequestMethodAction
/Subscription/{ID}GETGet Subscription by ID

2. Search

HTTP RequestMethodAction
/Subscription?[parameter={value}]GET

Parameters:

KeyTypeDescription
statusTokenThe current state of the subscription (active, requested, error, off)
typeTokenThe type of channel for the sent notifications

3. Delete

HTTP RequestMethodAction
/SubscriptionDELETEDeletes subscription

4. Create

HTTP RequestMethodAction
/SubscriptionPOSTCreates new subscription

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

ResourceAdditional attributes you can use in criteriaPayload
DiagnosticReport patient
category
* status
DocumentReference patient
class
* type
DocumentReference.OCRapplication/hg-ocr+json
RequestGroup* patient
ProcedureRequest* patient
FaxMessage direction
deliveryFailed
DirectMessage* direction
Patient gender
birthDate [eq, gt, lt]
* postalCode
Patient.P360application/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 NameDefinition
Dateday-name, day month year hour:minute:second GMT
DigestSHA-512 checksum of the payload
X-Hg-EventIdThe ID of the event
X-Hg-EventCreatedWhen the event was issued
X-Hg-SignatureHMAC 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 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)RequiredDescription
client_idYThe Oauth client ID assigned to Health Gorilla by the user
client_secretYThe Client Secret assigned to Health Gorilla by the user
scopeNThe scope required (if any) to allow Health Gorilla to send the notifications to the webhook
oauth_endpoint_urlYThe URL that will be used by Health Gorilla to authenticate.
headerName:headerValueNAny 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.

PathOperations
/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:

PayloadDescription
No payloadSee https://www.hl7.org/fhir/subscription.html#2.46.6.1 for details
application/fhir+xmlSee https://www.hl7.org/fhir/subscription.html#2.46.6.1 for details
application/fhir+jsonSee https://www.hl7.org/fhir/subscription.html#2.46.6.1 for details
application/hg-event+jsonHealth 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=” 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:

PropertyValue
Subscription.channel.typemessaging
Subscription.channel.endpointInclude operation $process-message
Subscription.channel.payloadapplication/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:

ParameterTypeDetailsRequired
message.eventtokenadmin-notifyYes
message.focusreferencepatient logical IDNo
_lastUpdateddateNo
_offsetnumberDefault: 0No
_countnumberDefault: 100No
eventTypestringOne of codes A01 - A62No
{{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:

Create a new subscription:

PropertyValue
Subscription.criteriaPatient.P360
Subscription.channel.payloadapplication/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" 
}