Webhooks

Webhooks offer a great way to automate the flow with other apps when invitees schedule, cancel or reschedule events, or when the meeting ends.

<iframe style={{ width:"100%",maxWidth:"560px" }} height="315" src="https://www.youtube.com/embed/Yy9me5E09LA?si=_2Mz-CKL2ajsFivd" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen />

The webhook subscription allows you to listen to specific trigger events, such as when a booking has been scheduled, for example. You can always listen to the webhook by providing a custom subscriber URL with your own development work. However, if you wish to trigger automations without any development work, you can use the integration with Zapier which connects Cal.com to your apps.

<Note> Please note that the webhooks can be associated with user as well as individual event types, including team event types. </Note>

Creating a webhook subscription

To create a new webhook subscription, visit /settings/developer/webhooks and proceed to enter the following details:

<Steps> <Step title="Subscriber URL"> This is the listener URL where the payload will be sent when an event trigger is activated. </Step> <Step title="Event triggers"> You can choose which specific triggers to listen to. Currently available triggers include: </Step> <Step title="Secret"> You can provide a secret key with this webhook to [verify it](/docs/core-features/webhooks#verifying-the-authenticity-of-the-received-payload) 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. </Step> <Step title="Custom Payload"> You have the option to [customize the payload](/docs/core-features/webhooks#adding-a-custom-payload-template) that you receive when a subscribed event is triggered. </Step> </Steps>

Webhook payload reference

All webhook payloads are wrapped in the following structure:

<Note> Webhook payloads are versioned. The version of the payload sent is included in the x-cal-webhook-version HTTP header. Example: x-cal-webhook-version: 2021-10-20 </Note>

Select a version and trigger event to view the example payload:

<Tabs> <Tab title="2021-10-20" id="2021-10-20"> <AccordionGroup> <Accordion title="BOOKING_CREATED"> ```json { "triggerEvent": "BOOKING_CREATED", "createdAt": "2024-01-01T00:00:00.000Z", "payload": { "bookerUrl": "https://app.example.com", "title": "Strategy Session between Organizer and Guest", "startTime": "2024-01-01T10:00:00Z", "endTime": "2024-01-01T10:15:00Z", "additionalNotes": "", "type": "standard-event-type", "description": "", "eventTypeId": 123, "hideCalendarNotes": false, "hideCalendarEventDetails": false, "hideOrganizerEmail": false, "schedulingType": null, "seatsPerTimeSlot": null, "seatsShowAttendees": true, "seatsShowAvailabilityCount": true, "customReplyToEmail": null, "disableRescheduling": false, "disableCancelling": false, "organizer": { "id": 1, "name": "Organizer Name", "email": "[email protected]", "username": "organizer-handle", "usernameInOrg": "organizer", "timeZone": "UTC", "language": { "locale": "en" }, "timeFormat": "h:mma", "utcOffset": 0 }, "attendees": [ { "email": "[email protected]", "name": "Guest User", "firstName": "Guest", "lastName": "User", "timeZone": "UTC", "language": { "locale": "en" }, "utcOffset": 0 }, { "email": "[email protected]", "name": "Additional Guest", "firstName": "", "lastName": "", "timeZone": "UTC", "language": { "locale": "en" }, "utcOffset": 0 } ], "customInputs": {}, "responses": { "name": { "label": "your_name", "value": "Guest User", "isHidden": false }, "email": { "label": "email_address", "value": "[email protected]", "isHidden": false }, "attendeePhoneNumber": { "label": "phone_number", "isHidden": true }, "location": { "label": "location", "value": { "optionValue": "", "value": "integrations:video-provider" }, "isHidden": false }, "title": { "label": "what_is_this_meeting_about", "isHidden": true }, "notes": { "label": "additional_notes", "isHidden": false }, "guests": { "label": "additional_guests", "value": [ "[email protected]" ], "isHidden": false }, "rescheduleReason": { "label": "reason_for_reschedule", "isHidden": false } }, "userFieldsResponses": {}, "location": "integrations:video-provider", "destinationCalendar": null, "iCalUID": "[email protected]", "iCalSequence": 0, "requiresConfirmation": false, "oneTimePassword": null, "organizationId": 1, "hashedLink": null, "uid": "unique-booking-id", "conferenceData": { "createRequest": { "requestId": "00000000-0000-0000-0000-000000000000" } }, "videoCallData": { "type": "video_provider", "id": "meeting-room-id", "password": "redacted_token", "url": "https://video.example.com/meeting-room-id" }, "appsStatus": [ { "appName": "video-app", "type": "video_provider", "success": 1, "failures": 0, "errors": [] } ], "eventTitle": "Strategy Session", "eventDescription": "", "price": 0, "currency": "usd", "length": 15, "bookingId": 100, "metadata": { "videoCallUrl": "https://app.example.com/video/unique-booking-id" }, "status": "ACCEPTED" } } ``` </Accordion> <Accordion title="BOOKING_CANCELLED"> ```json { "triggerEvent": "BOOKING_CANCELLED", "createdAt": "2024-01-01T15:00:00.000Z", "payload": { "bookerUrl": "https://app.example.com", "title": "Strategy Session: Organizer & Guest", "length": 15, "type": "standard-event-type", "additionalNotes": "Standard meeting notes placeholder", "description": "Standard meeting notes placeholder", "customInputs": {}, "eventTypeId": 100, "userFieldsResponses": {}, "responses": { "name": { "label": "name", "value": "Guest User" }, "email": { "label": "email", "value": "[email protected]" }, "notes": { "label": "notes", "value": "Standard meeting notes placeholder" }, "guests": { "label": "guests", "value": [ "[email protected]" ] }, "rescheduleReason": { "label": "rescheduleReason", "value": "Original slot no longer works." } }, "startTime": "2024-01-04T10:00:00+00:00", "endTime": "2024-01-04T10:15:00+00:00", "organizer": { "id": 1, "username": "organizer-handle", "usernameInOrg": "organizer", "email": "[email protected]", "name": "Organizer Name", "timeZone": "UTC", "timeFormat": "h:mma", "language": { "locale": "en" }, "utcOffset": 0 }, "attendees": [ { "name": "Guest User", "email": "[email protected]", "timeZone": "UTC", "phoneNumber": null, "language": { "locale": "en" }, "utcOffset": 0 }, { "name": "Additional Guest", "email": "[email protected]", "timeZone": "UTC", "phoneNumber": null, "language": { "locale": "en" }, "utcOffset": 0 } ], "uid": "unique-booking-identifier", "bookingId": 200, "location": "integrations:video-provider", "destinationCalendar": [], "cancellationReason": "I am no longer able to attend this session.", "seatsPerTimeSlot": null, "seatsShowAttendees": false, "iCalUID": "[email protected]", "iCalSequence": 2, "hideOrganizerEmail": false, "customReplyToEmail": null, "organizationId": 5, "eventTitle": "Strategy Session", "eventDescription": null, "requiresConfirmation": true, "price": null, "currency": "usd", "status": "CANCELLED", "requestReschedule": false } } ``` </Accordion> <Accordion title="BOOKING_RESCHEDULED"> ```json { "triggerEvent": "BOOKING_RESCHEDULED", "createdAt": "2024-01-01T10:00:00.000Z", "payload": { "bookerUrl": "https://app.example.com", "title": "Strategy Session: Organizer & Guest", "startTime": "2024-01-10T14:30:00Z", "endTime": "2024-01-10T14:45:00Z", "additionalNotes": "Standard meeting notes placeholder", "type": "standard-event-type", "description": "Standard meeting notes placeholder", "eventTypeId": 100, "hideCalendarNotes": false, "hideCalendarEventDetails": false, "hideOrganizerEmail": false, "schedulingType": null, "seatsPerTimeSlot": null, "seatsShowAttendees": true, "seatsShowAvailabilityCount": true, "customReplyToEmail": null, "disableRescheduling": false, "disableCancelling": false, "organizer": { "id": 1, "name": "Organizer Name", "email": "[email protected]", "username": "organizer-handle", "usernameInOrg": "organizer", "timeZone": "UTC", "language": { "locale": "en" }, "timeFormat": "h:mma", "utcOffset": 0 }, "attendees": [ { "email": "[email protected]", "name": "Guest User", "firstName": "Guest", "lastName": "User", "timeZone": "UTC", "language": { "locale": "en" }, "utcOffset": 0 }, { "email": "[email protected]", "name": "Additional Guest", "firstName": "", "lastName": "", "timeZone": "UTC", "language": { "locale": "en" }, "utcOffset": 0 } ], "customInputs": {}, "responses": { "name": { "label": "your_name", "value": "Guest User", "isHidden": false }, "email": { "label": "email_address", "value": "[email protected]", "isHidden": false }, "attendeePhoneNumber": { "label": "phone_number", "isHidden": true }, "location": { "label": "location", "value": { "value": "integrations:video-provider", "optionValue": "" }, "isHidden": false }, "title": { "label": "what_is_this_meeting_about", "isHidden": true }, "notes": { "label": "additional_notes", "value": "Standard meeting notes placeholder", "isHidden": false }, "guests": { "label": "additional_guests", "value": [ "[email protected]" ], "isHidden": false }, "rescheduleReason": { "label": "reason_for_reschedule", "isHidden": false } }, "userFieldsResponses": {}, "location": "integrations:video-provider", "destinationCalendar": null, "iCalSequence": 1, "requiresConfirmation": false, "oneTimePassword": null, "organizationId": 1, "hashedLink": null, "uid": "new-booking-unique-id", "videoCallData": { "type": "video_provider", "id": "meeting-room-id", "password": "redacted_jwt_token", "url": "https://video.example.com/meeting-room-id" }, "conferenceData": { "createRequest": { "requestId": "00000000-0000-0000-0000-000000000000" } }, "appsStatus": [ { "appName": "video-app", "type": "video_provider", "success": 1, "failures": 0, "errors": [] } ], "eventTitle": "Strategy Session", "eventDescription": "", "price": 0, "currency": "usd", "length": 15, "bookingId": 201, "rescheduleId": 200, "rescheduleUid": "previous-booking-unique-id", "rescheduleStartTime": "2024-01-05T14:30:00Z", "rescheduleEndTime": "2024-01-05T14:45:00Z", "metadata": { "videoCallUrl": "https://app.example.com/video/new-booking-unique-id" }, "status": "ACCEPTED" } } ``` </Accordion> <Accordion title="BOOKING_REQUESTED"> ```json { "triggerEvent": "BOOKING_REQUESTED", "createdAt": "2024-01-01T12:00:00.000Z", "payload": { "bookerUrl": "https://app.example.com", "title": "Strategy Session: Organizer & Guest", "startTime": "2024-01-01T13:00:00Z", "endTime": "2024-01-01T13:15:00Z", "additionalNotes": "Standard meeting notes placeholder", "type": "standard-event-type", "description": "Standard meeting notes placeholder", "eventTypeId": 100, "hideCalendarNotes": false, "hideCalendarEventDetails": false, "hideOrganizerEmail": false, "schedulingType": null, "seatsPerTimeSlot": null, "seatsShowAttendees": true, "seatsShowAvailabilityCount": true, "customReplyToEmail": null, "disableRescheduling": false, "disableCancelling": false, "organizer": { "id": 1, "name": "Organizer Name", "email": "[email protected]", "username": "organizer-handle", "usernameInOrg": "organizer", "timeZone": "UTC", "language": { "locale": "en" }, "timeFormat": "h:mma", "utcOffset": 0 }, "attendees": [ { "email": "[email protected]", "name": "Guest User", "firstName": "Guest", "lastName": "User", "timeZone": "UTC", "language": { "locale": "en" }, "utcOffset": 0 }, { "email": "[email protected]", "name": "Additional Guest", "firstName": "", "lastName": "", "timeZone": "UTC", "language": { "locale": "en" }, "utcOffset": 0 } ], "customInputs": {}, "responses": { "name": { "label": "your_name", "value": "Guest User", "isHidden": false }, "email": { "label": "email_address", "value": "[email protected]", "isHidden": false }, "attendeePhoneNumber": { "label": "phone_number", "isHidden": true }, "location": { "label": "location", "value": { "value": "integrations:video-provider", "optionValue": "" }, "isHidden": false }, "title": { "label": "what_is_this_meeting_about", "isHidden": true }, "notes": { "label": "additional_notes", "value": "Standard meeting notes placeholder", "isHidden": false }, "guests": { "label": "additional_guests", "value": [ "[email protected]" ], "isHidden": false }, "rescheduleReason": { "label": "reason_for_reschedule", "isHidden": false } }, "userFieldsResponses": {}, "location": "integrations:video-provider", "destinationCalendar": null, "iCalUID": "[email protected]", "iCalSequence": 0, "requiresConfirmation": true, "oneTimePassword": "00000000-0000-0000-0000-000000000000", "organizationId": 1, "hashedLink": null, "uid": "unique-booking-id", "eventTitle": "Strategy Session", "eventDescription": "", "price": 0, "currency": "usd", "length": 15, "bookingId": 200, "metadata": {}, "status": "PENDING" } } ``` </Accordion> <Accordion title="BOOKING_REJECTED"> ```json { "triggerEvent": "BOOKING_REJECTED", "createdAt": "2024-01-01T14:00:00.000Z", "payload": { "type": "standard-event-type", "title": "Strategy Session: Organizer & Guest", "description": "Standard meeting notes placeholder", "bookerUrl": "https://app.example.com", "userFieldsResponses": {}, "responses": { "name": { "label": "name", "value": "Guest User" }, "email": { "label": "email", "value": "[email protected]" }, "notes": { "label": "notes", "value": "Standard meeting notes placeholder" }, "guests": { "label": "guests", "value": [ "[email protected]" ] } }, "customInputs": {}, "startTime": "2024-01-01T15:00:00.000Z", "endTime": "2024-01-01T15:15:00.000Z", "organizer": { "id": 1, "email": "[email protected]", "name": "Organizer Name", "username": "organizer-handle", "usernameInOrg": "organizer", "timeZone": "UTC", "timeFormat": "h:mma", "language": { "locale": "en" }, "utcOffset": 0 }, "attendees": [ { "name": "Guest User", "email": "[email protected]", "timeZone": "UTC", "phoneNumber": null, "language": { "locale": "en" }, "utcOffset": 0 }, { "name": "Additional Guest", "email": "[email protected]", "timeZone": "UTC", "phoneNumber": null, "language": { "locale": "en" }, "utcOffset": 0 } ], "location": "integrations:video-provider", "uid": "unique-booking-identifier", "destinationCalendar": [], "requiresConfirmation": true, "hideOrganizerEmail": false, "hideCalendarNotes": false, "hideCalendarEventDetails": false, "eventTypeId": 100, "customReplyToEmail": null, "organizationId": 5, "additionalNotes": "Standard meeting notes placeholder", "rejectionReason": "The organizer is no longer available at this time.", "eventTitle": "Strategy Session", "eventDescription": "", "price": 0, "currency": "usd", "length": 15, "bookingId": 200, "status": "REJECTED" } } ``` </Accordion> <Accordion title="BOOKING_PAID"> ```json { "triggerEvent": "BOOKING_PAID", "createdAt": "2024-01-01T12:00:00.000Z", "payload": { "type": "Consultation Session", "title": "Consultation Session: Organizer & Guest", "description": "", "additionalNotes": "", "customInputs": {}, "startTime": "2024-01-02T10:00:00.000Z", "endTime": "2024-01-02T10:30:00.000Z", "organizer": { "id": 1, "name": "Organizer Name", "email": "[email protected]", "username": "organizer-handle", "timeZone": "UTC", "language": { "locale": "en" }, "timeFormat": 12 }, "attendees": [ { "name": "Guest User", "email": "[email protected]", "timeZone": "UTC", "language": { "locale": "en" } } ], "location": "integrations:video-provider", "destinationCalendar": null, "hideCalendarNotes": false, "requiresConfirmation": true, "eventTypeId": 50, "seatsShowAttendees": true, "seatsShowAvailabilityCount": true, "schedulingType": null, "iCalUID": "[email protected]", "iCalSequence": 0, "uid": "unique-booking-uid", "bookingId": 100, "eventTitle": "Consultation Session", "eventDescription": "", "price": 1000, "currency": "USD", "length": 30, "paymentId": 500, "metadata": { "identifier": "platform.name", "bookingId": 100, "eventTypeId": 50, "bookerEmail": "[email protected]", "eventTitle": "Consultation Session", "externalId": "pi_0000000000000000" }, "status": "ACCEPTED" } } ``` </Accordion> <Accordion title="BOOKING_PAYMENT_INITIATED"> ```json { "triggerEvent": "BOOKING_PAYMENT_INITIATED", "createdAt": "2024-01-01T12:00:00.000Z", "payload": { "type": "Consultation Session", "title": "Consultation Session: Organizer & Guest", "description": "", "additionalNotes": "", "customInputs": {}, "startTime": "2024-01-02T10:00:00.000Z", "endTime": "2024-01-02T10:30:00.000Z", "organizer": { "id": 1, "name": "Organizer Name", "email": "[email protected]", "username": "organizer-handle", "timeZone": "UTC", "language": { "locale": "en" }, "timeFormat": 12 }, "attendees": [ { "name": "Guest User", "email": "[email protected]", "timeZone": "UTC", "language": { "locale": "en" } } ], "location": "integrations:video-provider", "destinationCalendar": null, "hideCalendarNotes": false, "requiresConfirmation": false, "eventTypeId": 50, "seatsShowAttendees": true, "seatsShowAvailabilityCount": true, "schedulingType": null, "iCalUID": "[email protected]", "iCalSequence": 0, "uid": "unique-booking-uid", "bookingId": 100, </Tab> </Tabs>

Booking No-show Updated webhook payload

This webhook is triggered when an attendee is manually marked or unmarked as no-show on the /bookings/past page.

Example payload when marking an attendee as no-show:

Example payload when unmarking an attendee as no-show:

Cal Video No-Show Detection webhooks

These webhooks are triggered automatically when hosts or guests don't join a Cal Video meeting within the configured time after the booking starts. Unlike BOOKING_NO_SHOW_UPDATED which requires manual action, these are detected automatically by checking Cal Video participant data.

<Note> These webhooks only work for bookings that use Cal Video as the meeting location. </Note>

Example payload when host didn't join (AFTER_HOSTS_CAL_VIDEO_NO_SHOW):

Example payload when guest didn't join (AFTER_GUESTS_CAL_VIDEO_NO_SHOW):

Verifying the authenticity of the received payload

<Steps> <Step title="Add a new secret key to your webhook"> Simply add a new **secret key** to your webhook configuration and save it. </Step> <Step title="Wait for the webhook to be triggered"> The webhook will trigger when an event is created, cancelled, rescheduled, or when a meeting ends. </Step> <Step title="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. </Step> <Step title="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. </Step> </Steps>

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:

where {{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, BOOKING_NO_SHOW_UPDATED, AFTER_HOSTS_CAL_VIDEO_NO_SHOW, AFTER_GUESTS_CAL_VIDEO_NO_SHOW, WRONG_ASSIGNMENT_REPORT]
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	Email	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")