The Enterprise API Event Notification Service (ENS) is a feature allowing an API Consumer to receive notifications whenever one or more specific events occur in your account, via a webhook mechanism.
For example, when an appointment is created in your account, a notification that contains details about that appointment is immediately sent to a callback URL you set when creating a subscription.
Security
Listening to a webhook implies exposing a URL (the webhook endpoint) to the web. Because anyone can call the webhook endpoint, it wouldn’t be advised to blindly action any requests received at this endpoint. To help you identify requests from your account, the CHR signs each notification with a "secret". The resulting signature is included in the request header. Before proceeding with any program execution, you can use this signature to verify that the notification came from your CHR account. For details on configuring your secret, go to Creating a new subscription.
📌 Note: For added security, the notification payload does not contain personal information or personal health information. Only a set of fields is supplied to allow you to retrieve the complete data related to the event via an API query.
Delivery retries
The recipient of the notifications should send a '2XX' HTTP response status code back to let the ENS know that the notification was received. If a notification fails for any reason, the ENS uses a backoff mechanism to retry sending the request to your endpoint 5 times: after 5, 10, 20, 60 and 120 minutes. There are no retries for notification delivery if the server responds with the '410 Gone' HTTP status.
Creating a new subscription
To receive notifications, you need to create a subscription and select the events for which you want to be notified.
Steps
Gather the required information to configure your subscription:
Subscription URL: URL that receives the HTTP Post requests.
Secret: Text string used to create the signature for each notification.
Log in to the CHR as a user with permissions to access the Enterprise API settings.
From the main menu, click Settings > Enterprise API. The list of existing consumers appears.
Click the pencil icon next to the appropriate API consumer. The Edit API consumer window opens.
Click the Subscriptions tab. Any existing subscriptions are displayed.
Click + New Subscription. The Add Subscription window appears.
In the Subscription name field, enter a name to describe the subscription.
In the Subscription URL field, enter the URL to which the notifications will be directed.
In the Secret field, enter the text string that will be used to create the signature (refer to Security).
Select one or more topics from the Event topics section, based on the events for which you want to receive notifications.
Click Accept.
📌 Note: Subscriptions are activated immediately upon creation; you can deactivate a subscription by clicking the deactivate icon for the desired subscription.
Notification payloads
Each notification delivers its payload in a JSON format. The notification payload contains only IDs and other fields, no personal information or personal health information. You can use these IDs in a query to retrieve the required information for your API consumer. Some fields are unique while others are shared between all event topics.
Each notification payload includes the following fields:
topic
subscriptionId
accountDomain
Below is a list of the event topics and the additional fields returned:
Event topic | Fields |
appointment.canceled appointment.created appointment.deactivated appointment.updated | appointmentId patientId providerId locationId serviceId visitType startAt changedFields status tagIds |
patient_demographics.archived patient_demographics.created patient_demographics.updated
| patientId primaryPractitionerId primaryLocationId changedFields statusTagIds |
qnaire.completed | questionnaireResponseId patientId providerId questionnaireId |
Updated March 27, 2024