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 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 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=” 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"
}
Updated 4 months ago