TABLE OF CONTENT

• Introduction
• Requirements
• Setting up webhooks in Calenso
  • Step-by-step guide to configuration
• Payload-Analysis
• Available webhook event types
• Planned webhook event types for the future
• Use cases
• Summary

Introduction

Webhooks allow a system to notify another system when a specific event occurs. Instead of an application continuously polling for new events, a webhook informs other applications immediately when an event happens. This significantly reduces the message traffic between applications.

Requirements

The use of webhooks in Calenso is available in all subscriptions. Each subscription allows a different number of endpoints.

You also need a system that can accept webhooks as POST calls.

Setting up webhooks in Calenso

Step-by-step guide to configuration

Go to Webhooks under Settings.

Click on Enable Webhooks.

New webhook endpoints can be added via the "Plus" symbol.

Enter the URL of the webhook endpoint. It is possible to define multiple endpoints from the Professional-licence upwards.

Optional: If the system is secured, an Authorisation Header can be configured. To do this, click on Header Key to define the key. A possible value would be "Authorisation" or "Ocp-Apim-Subscription-Key".

Define the Authorisation Header Value as required.

Optional: Define whether the JSON file should be sent to a specific email address. In this case, no more requests are made to the defined endpoint.

Define the desired webhook event types and the hierarchy of the JSON file that transmits the webhook data.

Every time a customer books an appointment or event, a webhook request is automatically sent to the configured URL. Next to each endpoint you will find the corresponding statistics, which provide information about whether the requests were accepted by the server (status code 2xx).

More detailed information (including the payload of the requests) can be found below. First select the desired endpoint.

After the respective time stamp, you can see whether the call was successful based on the status and the HTTP code.

Under "Actions", you can use "Raw" to display the raw data, download it or trigger the webhook again. Webhooks that are triggered multiple times are labelled accordingly.

After 60 days, the webhook requests are archived. This means that the webhook request data is no longer available and is deleted. Replay, raw and download actions are greyed out and an "Archived" note is inserted under the date.

Payload-Analysis

If you want to view the payload of the request, click on "Raw". There you can examine the JSON payload in more detail.

Available webhook event types

Calenso currently supports the following webhook event types:

• appointment.booking.created: A customer has booked an appointment via the booking widget with the partner.
• event.booking.created: A customer has registered for a group event via the booking widget.
• appointment.booking.cancelled: A customer has canceled an appointment with the partner (from version 3.1.6).
• event.booking.cancelled: A customer has canceled their event participation (from v3.1.6).
• appointment.updated: The appointment has been rescheduled.
• appointment.manual.booking.created: A manual customer appointment has been entered in the partner's calendar (from v3.8.0).
• event.manual.booking.created: A customer has been manually added to a group event by the partner (from v3.8.0).
• customer.created: A customer has been created (from v4.9.0).
• customer.updated: A customer has been updated (from v4.9.0).
• customer.deleted: A customer has been deleted (from v4.9.0).
• lead.created: A new lead has been created (included only in Enterprise functions).

Planned webhook event types for the future

• appointment.booking.payment_succeeded: The booked services have been successfully paid.
• appointment.booking.payment_failed: There was a problem with the payment for the booked services.
• event.booking.payment_succeeded: The event participation has been successfully paid.
• event.booking.payment_failed: There was a problem with the payment for the event participation.

Use cases

When to Use Webhooks?

Webhooks are particularly useful when an ERP system needs to be informed about appointment or event bookings to trigger further actions or to save the booking data.

Summary

Webhooks in Calenso offer an efficient way to inform other systems about events. They are available in the Whitelabel and Enterprise subscriptions and allow flexible and secure integration into existing workflows.

You can also find more details about webhooks in our documentation.