API Guide – Subscriptions and Events

[SLeon]

ApiEvents are webhooks sent to a developer’s webhook site when certain changes occur in Open Dental. There are two types of ApiEvents:

• UiEvents occur when a user has taken a certain action on their workstation. For example, the PatientSelected event will fire whenever a new patient is selected within an instance of Open Dental.
• DbEvents occur when any column has changed in a specific database table. This change could be made through an instance of Open Dental or the API.

Subscriptions are how developers subscribe to receive ApiEvent webhooks. They are highly customizable to suit the needs of many different implementations.

You can use a simple webhook site for initial testing, such as Webhook.site or similar.

Subscribing to an Event

This example will subscribe to the Appointment database event. This can be used to keep a list of appointments up to date.

1. Create a Subscription

Use the Subscriptions POST API method to create the subscription. Include a JSON body similar to what is shown below, but be sure to use your current machine name for the Workstation field:

Code: Select all

{
  "EndPointUrl": "https://myserver/apievents/",
  "Workstation": "MOLLYR", 
  "WatchTable": "Appointment",
  "PollingSeconds": 5 
}

Your return result will look like this:

Code: Select all

{
  "SubscriptionNum": 1,
  "EndPointUrl": "https://myserver/apievents/",
  "Workstation": "MOLLYR", 
  "CustomerKey": /*YourCustomerAPIKey*/,
  "WatchTable": "Appointment",
  "PollingSeconds": 5,
  "UiEventType": "",
  "DateTimeStart": "2022-11-28 15:04:31",
  "DateTimeStop": "0001-01-01 00:00:00",
  "Note": ""
}

Note that the CustomerKey field is derived from the Authorization header of the API request and DateTimeStart is moment Subscription was created. This particular subscription will cause Open Dental to send a webhook to your EndPointUrl when a change has been made to this customer’s appointment table. Subscriptions are stored in the dental office database in the ApiSubscription table.

2. Process the Subscription

There are two ways a Subscription can be processed:

• OpenDental.exe running on a workstation can process both UI and Database Events.
• OpenDentalAPIService.exe running on a server can only process Database Events (no UI).

Our example will walk through this first option, so launch Open Dental on the machine specified in the Subscription from Step 1.

At the interval specified in your subscription’s PollingSeconds, Open Dental will look for changes that occurred in the WatchTable since the DateTimeStart. In our example, the following occurs:

1. Examine all subscriptions that apply to the current workstation (“MOLLYR”) or all workstations (left blank, “”).
2. Exclude any expired subscriptions (DateTimeStop field is before the current time).
3. Determine if it is time to check the database for changes. This is true when the current time is equal to or later than DateTimeStart + PollingSeconds (2022-11-28 15:04:31 + 00:00:05).
4. Open Dental will query the appointment table for rows with DateTStamp values equal to or greater than DateTimeStart (2022-11-28 15:04:31)
5. If any rows meet these criteria, they are sent to your EndPointUrl in a single webhook.

Sending the Event

Now we will make a change to the appointment table of this database to trigger an event. This change can occur in two ways:

• Through the API’s Appointments PUT and POST methods. All API modes will trigger an event.
• Through OpenDental.exe on a workstation. Any change made on any workstation will trigger an event.

This example will demonstrate both. First make a new appointment with the API. Send the following JSON to our Remote API endpoint https://api.opendental.com/api/v1/appointments:

Code: Select all

{
    "PatNum": 10,
    "AptDateTime": "2022-12-02 13:30:00",
    "Op": 1
}

Your request will return a response including all the information pertaining to this new appointment. Check your webhook service for this new event. Its body will be identical to the JSON returned in your API request. If you do not see this event, see the Troubleshooting section at the end of this guide.

Now we will edit this appointment within Open Dental to trigger an event. In the Appointment Module, double click on the appointment we just created. Any change made to the appointment will cause an event to fire, but let’s update the Confirmed field to “Confirmed”. Click OK to save your changes and fire an event. On your webhook site, the body of this event will be identical to the first except for the updated Confirmed field.

Additional Notes

An ApiEvent will not fire if there is nothing to send; they will be sent only when a change has occurred.

Only one ApiEvent will fire per PollingSeconds interval per Subscription. In the above example, if three appointments were added in our 5 second interval, a single event will fire. This event will contain the list of three appointments.

When a Subscription is processed the DateTimeStart is updated to the current time. Therefore, you can see that the subscription is active/being processed because this field will be incremented by PollingSeconds. This incrementing occurs regardless of if there were changes requiring an event to be fired.

The Workstation specified in the Subscription is important. If the field is left blank, all instances of Open Dental will fire the same database event (duplicates). Most subscriptions for database events will specify a workstation. Because the API Service can fire database events, we recommend setting the Subscription.Workstation to the machine on which it is installed. This has the added benefit of processing subscriptions/firing events during the off hours when typical workstations are not running Open Dental.

UiEvents fire immediately and do no utilize a PollingSeconds parameter. Most subscriptions for UiEvents are used for applications installed on each workstation. Therefore, these developers will likely leave the Workstation field blank (so that all machines fire) and use an EndPointUrl containing “localhost”.

Finally, the EndPointUrl of the Subscription can be used in a multitude of ways. Query parameters can be included in this string that your webhook service can use in its parsing logic such as “https://myserver/apievents?type=patientdb”). See an in-depth discussion on this here.

Update: More information has been added to the headers of API event webhooks. The name of the machine that sent the event can be found in the "Workstation" header as of version 22.4.28. Similarly, the type of event fired (e.g. "WatchTable: Appointment") can be found in the "Event-Type" header starting in 22.4.35.

Troubleshooting

Unable to see an event on your webhook service:

• Ensure an instance of Open Dental (or the API Service) is running to process the subscription.
• Ensure the workstation of the subscription either 1) matches the machine running Open Dental/API Service, or 2) is blank. Events will not fire if there is a mismatch.
• For Database events, use Subscriptions GET a few times to see that the DateTimeStart is incremented by PollingSeconds. This will not occur if there is an issue processing the subscription due to the above reasons.
• For database events, make sure the action you are performing actually changes the database. Updating an Appointment’s Confirmed status from “Unconfirmed” to “Unconfirmed” does not actually change the data in the appointment table, and an event will not fire.
• Similarly, selecting the same patient repeatedly will not fire the PatientSelected UiEvent.
• Ensure the EndPointUrl of your Subscription is accurate. Check the documentation of your webhook service for required formatting. Support for some characters (such as trailing ‘/’) varies widely.

Seeing duplicate events:

• Ensure the Workstation of your subscription specifies a machine name for database events. Leaving this field blank will cause all instances of Open Dental at the dental office to fire the same event.
• If a Workstation is specified, make sure there is only one instance of Open Dental open on the machine processing subscriptions. Having an instance of Open Dental and the API Service running on the specified machine would also produce this result.