By default, every API client operates using an asynchronous notification flow. This means that Docplanner/Doctoralia notifies third-party systems about relevant events as they occur, rather than waiting for their immediate response. Each notification is expected to be acknowledged with a 2XX HTTP status code; if delivery fails, Docplanner will automatically retry.

How does this work in practice?

Consider the booking scenario:

• Asynchronous flow (default): When a user books a slot, the system does not wait for a response from the third-party integration. If a slot appears available, the booking proceeds immediately. Docplanner sends a slot-booked notification and displays a success message to the user, regardless of the third party’s response. If the third party returns a 4XX or 5XX status code (failure), Docplanner will attempt to resend the notification three times—after 1, 5, and 15 minutes.
• In most cases, this approach is sufficient and reliable. Issues may arise only in rare "race condition" scenarios, such as if a clinic and marketplace user attempt to book the same slot at precisely the same time. However, these edge cases are uncommon and typically do not impact system integrity.

Reducing the risk of race conditions

For high-volume environments (e.g., large clinics with numerous simultaneous bookings) where the risk of race conditions increases, Docplanner offers a real-time booking flow. This option is enabled on a per-API-client basis and does not require software-specific configuration.

In the real-time booking flow:

• An additional request is sent to the third-party endpoint at the end of the booking process to verify that the slot is still available and valid for booking.
• Only after receiving a successful response (2XX status code) from the third-party system is the slot confirmed and the booking finalized.

The diagram below illustrates this process:

When using the real-time booking model, you can also implement custom error messages to inform users about specific reasons for booking failures.