Skip to main content
All CollectionsCHR Enterprise API
CHR Enterprise API Event Notifications
CHR Enterprise API Event Notifications
Updated over a week ago

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

  1. Gather the required information to configure your subscription:

    1. Subscription URL: URL that receives the HTTP Post requests.

    2. Secret: Text string used to create the signature for each notification.

  2. Log in to the CHR as a user with permissions to access the Enterprise API settings.

  3. From the main menu, click Settings > Enterprise API. The list of existing consumers appears.

  4. Click the pencil icon next to the appropriate API consumer. The Edit API consumer window opens.

  5. Click the Subscriptions tab. Any existing subscriptions are displayed.

  6. Click + New Subscription. The Add Subscription window appears.

  7. In the Subscription name field, enter a name to describe the subscription.

  8. In the Subscription URL field, enter the URL to which the notifications will be directed.

  9. In the Secret field, enter the text string that will be used to create the signature (refer to Security).

  10. Select one or more topics from the Event topics section, based on the events for which you want to receive notifications.

  11. 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

Did this answer your question?