There are two possible ways to be notified about events.

• Pulling notifications constantly from our endpoint.
• Or we will be pushing notifications to your endpoint.

You can either use one or both of them.

There are few notification types:

• slot-booking (optional) When patient is about to book a visit, our system sends a notification to the specified 3rd party webhook, if 3rd party responds with 2xx HTTP Status Codes to the request the visit will be approved, any other status code except 2xx HTTP Status Codes block the booking flow (see more in Real-time requests (opens new window) section). The request can be used to check whether given slot is still available or all required data are valid.

  :::Tip Optional notification

  Note: that this notification is optional and will be enabled on request of the client

  :::

• slot-booked When patient books a visit from a doctor or doctor books a visit from their calendar.

• booking-canceled When patient or doctor cancels a visit.

• booking-moved When doctor or patient changes the date or hour of the booking.

• booking-moving When patient is about to change a date or hour of a visit our system sends a notification to the specified 3rd party webhook, if 3rd party responds with 2xx HTTP Status Codes to the request the visit will be moved. Anything except 2xx HTTP Status Codes will not allow moving.

  This notification is optional and will be enabled on request of the 3rd party.

• break-created When doctor created a break in their Docpalnner calendar.

• break-moved When doctor moves a break in their Docplanner calendar.

• break-removed When doctor deleted the break from their calendar.

• presence-marked When presence was marked by doctor or patient.

The detailed structure of callback notifications can be found in our API documentation here (opens new window).

PUSH Notifications

For the sake of using PUSH communication method, partner needs to provide properly configured endpoint. We require using HTTPS to ensure communication security. All the requests will be sent from a single IP address (to get more details contact us directly). Additionally Docplanner supports authorization via API Key Authorization header. If you'd like to use this kind of security layer, please contact local integrations specialist to exchange neccessary data.

The endpoint should be provided with each customer's activation (see Activation process section (opens new window))

HTTP POST method will be used to push event data to endpoint.

Sending push events

In case of unsuccessful delivery of an event (status code different than 2XX) notifications will be sent 2 more times, after 5 and 10 minutes. In case of not processing them correctly, the notifications are buried and can be only re-triggered manually.

Fetching failed notifications

In the PUSH notification model, there's always a risk that some notifications might not be successfully processed - there are number of possible reasons including temporary downtimes of the server, misconfigurations etc. As you could have learned from the paragraph above, Docplanner will try sending you notification 3 times (in the interval of 5 minutes) but if all the attempts fail (status code from your endpoint different than 2XX), notification will be removed from the queue. In that case you can still recover the missing message. In order to do this, you need to call our Release Notifications (opens new window) endpoint.

The logics of that operation is pretty straightforward. Whenever you call the endpoint, we will queue again all the messages that were failed to process. All failed messages are permanently deleted after 14 days from creation date.

The process of releasing notifications can be triggered 1 time every 60 minutes if you try to call Release Notification endpoint sooner than 60 minutes from the previous operation, it will end up with 429 error code (the value of header Retry-After contains number of seconds until the lock is removed).

Fetching failed messages periodically

Since some of the messages might be crucial business-wise (bookings, cancellations etc) we strongly recommend running the process of releasing failed notifications periodically (i.e once a day)

PULL Notifications

You can pull notifications via our endpoint:

https://www.{domain}/api/v3/integration/notifications

This page will respond to you with the earliest notification you haven’t been pulled yet. First In First Out (FIFO) principle applied here.

This endpoint will respond with one notification per request until there aren’t any notifications left in the notification stack.

Maintaining pull process

Notifications that are not pulled in 72 hours are marked as expired and deleted from the system

Thanks to the new developments, we have added a new API endpoint allowing to pull multiple notifications within a single call. In order to achieve it, you need to call our Pull Multiple Notification (opens new window) endpoint:

https://www.{domain}/api/v3/integration/notifications/multiple

You should apply limit query parameter to the URL defining the maximal number of records to be returned. Currently, you can pull up to 100 notifications at once. If the parameter is not specified - a default value of 1 will be applied.