DOCPLANNER INTEGRATIONS

Push vs Pull

Events relevant to partner systems are communicated through notifications generated by the Docplanner application. These notifications can be either pushed to the partner's endpoint or pulled from the Docplanner notifications endpoint.

Docplanner supports two methods for partners to be notified about key events:

  • Pull: Your system regularly fetches notifications from our endpoint.
  • Push: Docplanner sends notifications directly to your defined endpoint.

You may use either method individually, or implement both simultaneously for redundancy.

Notification Types

The following notification events are available:

  • slot-booking (optional): Triggered when a patient initiates the process of booking a visit. The notification is sent to your webhook. If your endpoint returns any 2xx HTTP status code, the booking will proceed. Any other status code blocks the booking flow. See more in Real-time requests.

    Optional notification

    This notification is optional and can be enabled upon customer request.

  • slot-booked: Generated when a visit is successfully booked, either by a patient or directly by the doctor.
  • booking-canceled: Sent when an appointment is canceled by either the patient or the doctor.
  • booking-moved: Sent when the date or time of a booking is changed by either party.
  • booking-moving (optional): Triggered when a patient initiates a change of the appointment time or date. If your system responds with a 2xx status code, the booking will be moved; otherwise, the change is blocked. This notification is optional and available upon request.
  • break-created: Sent when a break is added to a doctor’s calendar.
  • break-moved: Sent when a break is rescheduled within a doctor’s calendar.
  • break-removed: Sent when a break is removed from the calendar.
  • presence-marked: Issued when patient presence is marked by either the doctor or the patient.

For complete notification payloads and details, refer to the API documentation here.

PUSH Notifications

To use the PUSH model, partners must provide a correctly configured HTTPS endpoint. All notifications are sent via HTTP POST from a single IP address (contact us for details). Docplanner also supports API Key authorization in the request header. Please coordinate with your local integration specialist to arrange necessary credentials and endpoint setup. The endpoint should be submitted during customer activation (see Activation process).

Unsuccessful Push Notifications

If a notification cannot be delivered (non-2xx status code), Docplanner retries delivery two more times—after 5 and 10 minutes. If all attempts fail, the notification is buried and must be manually re-triggered.

Fetching Failed Notifications

Despite retries, some notifications may not be processed due to network downtime, configuration errors, or other issues. If all delivery attempts fail, you can recover missed messages by calling our Release Notifications endpoint. This operation queues all failed notifications for your endpoint to receive again.

Important:

  • Failed notifications are permanently deleted 14 days after creation.
  • The release process can be triggered only once every 60 minutes. Attempts to call the endpoint more frequently will result in a 429 error, with the Retry-After header indicating when the lock will expire.

Periodic Release of Failed Notifications

As some notifications (e.g., booking or cancellation events) are business-critical, we recommend triggering the release process regularly (e.g., once per day) to recover any missed events.

PULL Notifications

Notifications can also be retrieved by polling:

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

This endpoint returns the earliest available notification not yet pulled, following a FIFO (First In, First Out) queue. Each request retrieves a single notification, until the stack is empty.

Managing the Pull Process

Notifications not pulled within 72 hours of creation are automatically expired and deleted from our system.

To improve efficiency, Docplanner provides an API endpoint to fetch multiple notifications in a single call:

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

Use the limit query parameter to specify how many notifications to return (up to 100 per request). If not specified, the default is 1.