Please note that the webhooks can be associated with user as well as individual event types, including team event types.
Creating a webhook subscription
To create a new webhook subscription, visit/settings/developer/webhooks
and proceed to enter the following details:
1
Subscriber URL
This is the listener URL where the payload will be sent when an event trigger is activated.
2
Event triggers
You can choose which specific triggers to listen to. Currently available triggers include:
Booking Cancelled
Booking Created
Booking Rescheduled
Booking Rejected
Booking Requested
Booking Payment Initiated
Booking Paid
Meeting Started
Recording Ready
Form Submitted
Meeting Ended
Instant Meeting Created
3
Secret
You can provide a secret key with this webhook to verify it on the subscriber URL when receiving a payload. This helps confirm whether the payload is authentic or has been tampered with. You can leave it blank if you don’t wish to secure the webhook with a secret key.
4
Custom Payload
You have the option to customize the payload that you receive when a subscribed event is triggered.
An example webhook payload
Verifying the authenticity of the received payload
1
Add a new secret key to your webhook
Simply add a new secret key to your webhook configuration and save it.
2
Wait for the webhook to be triggered
The webhook will trigger when an event is created, cancelled, rescheduled, or when a meeting ends.
3
Create an HMAC using the secret key
Use the secret key to create an HMAC, and update it with the webhook payload received to generate an SHA256 hash.
4
Verify the payload authenticity
Compare the hash received in the header of the webhook
(x-cal-signature-256)
with the one you created using the secret key and the body of the payload. If they don’t match, the received payload has been adulterated and cannot be trusted.Adding a custom payload template
Customizable webhooks are a great way reduce the development effort and in many cases remove the need for a developer to build an additional integration service. An example of a custom payload template is provided here:{{type}}
represents the event type slug and {{title}}
represents the title of the event type. Note that the variables should be added with a double parenthesis as shown above. Here’s a breakdown of the payload that you would receive via an incoming webhook, with an exhaustive list of all the supported variables provided below:
Webhook variable list
Variable | Type | Description |
---|---|---|
triggerEvent | String | The name of the trigger event [BOOKING_CREATED, BOOKING_RESCHEDULED, BOOKING_CANCELLED, MEETING_ENDED, BOOKING_REJECTED, BOOKING_REQUESTED, BOOKING_PAYMENT_INITIATED, BOOKING_PAID, MEETING_STARTED, RECORDING_READY, FORM_SUBMITTED] |
createdAt | Datetime | The time of the webhook |
type | String | The event type slug |
title | String | The event type name |
startTime | Datetime | The event’s start time |
endTime | Datetime | The event’s end time |
description | String | The event’s description as described in the event type settings |
location | String | Location of the event |
organizer | Person | The organizer of the event |
attendees | Person[] | The event booker & any guests |
uid | String | The UID of the booking |
rescheduleUid | String | The UID for rescheduling |
cancellationReason | String | Reason for cancellation |
rejectionReason | String | Reason for rejection |
team.name | String | Name of the team booked |
team.members | String[] | Members of the team booked |
metadata | JSON | Contains metadata of the booking, including the meeting URL (videoCallUrl) in case of Google Meet and Cal Video |
Person Structure
Variable | Type | Description |
---|---|---|
name | String | Name of the individual |
Email of the individual | ||
timezone | String | Timezone of the individual (e.g., “America/New_York”, “Asia/Kolkata”) |
language?.locale | String | Locale of the individual (e.g., “en”, “fr”) |