| title | 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 width="100%" height="100%" src="https://www.youtube.com/embed/Yy9me5E09LA?si=bhjQfHegY-ImFQYH" 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.
Webhooks can be created at multiple levels of scope, each determining which events they apply to:
-
User-level: Triggers for all booking links owned by the user (excluding team-managed types).
-
Booking-link level: Triggers only for a specific booking link. Useful for fine-grained control.
-
Team-level: Applies to team booking links (i.e., Collective and Round Robin) within the specified team.
In the case of Templates, bookings are made on the child booking links, not the parent team event. Because of this, team-level webhooks will **not** trigger for templates unless one of the following is true:- You create a webhook directly on the parent booking link (recommended), or
- You create individual webhooks on the child booking links (owned by users).
💡 Note: Users can create webhooks that apply to their own booking links, including child events under a template, even if a team-level webhook exists.
-
Organization-level: Applies to all team booking links across all teams within the organization.
To create a new webhook subscription, visit /settings/developer/webhooks and proceed to enter the following details:
-
Subscriber URL: The listener URL where the payload will be sent to, when an event trigger is triggered.
The subscriber URL must meet the following requirements:
- Cal.com SaaS: Only HTTPS URLs are accepted. HTTP, private/internal IP addresses (e.g.,
10.x.x.x,192.168.x.x,127.0.0.1), andlocalhostare blocked. - Self-hosted: Both HTTP and HTTPS URLs are accepted, and private IP addresses are allowed for internal webhooks.
- All environments: Cloud metadata endpoints (e.g.,
169.254.169.254) and non-HTTP protocols (e.g.,ftp://,file://) are always blocked.
If your subscriber URL does not meet these requirements, the webhook creation request will be rejected with an error.
- Cal.com SaaS: Only HTTPS URLs are accepted. HTTP, private/internal IP addresses (e.g.,
-
Event triggers: You can decide which triggers specifically to listen to. Currently, we offer listening to
Booking Cancelled,Booking Created,Booking Rescheduled,Booking Rejected,Booking Requested,Booking Paid,Booking Payment Initiated,Booking No-Show Updated,Meeting Started,Meeting Ended,Recording Ready,Recording Transcription Generated,Instant Meeting Created,Instant Meeting Accepted,Out of Office Created,After Hosts Cal Video No-Show,After Guests Cal Video No-Show,Form Submitted,Form Submitted (No Event),Calendar Entry Rejected, andDelegation Credential Rotation Required. -
Secret: You can provide a secret key with this webhook and then verify it on the subscriber URL when receiving a payload to confirm if the payload is authentic or adulterated. You can leave it blank, if you don't wish to secure the webhook with a secret key.
-
Custom Payload: You have the option to customize the payload you receive when a subscribed event is triggered.
-
Custom headers: You can add your own HTTP headers, such as an API key, to every delivery. See Adding custom headers.
| Event | Triggers When... |
|---|---|
| Booking Created | A new booking is successfully created. |
| Booking Cancelled | A booking is cancelled by the host, attendee, or via API. |
| Booking Rejected | A booking request is explicitly rejected by the host. |
| Booking Requested | A booking requiring confirmation from the host is submitted. |
| Booking Paid | Payment for a booking is completed. |
| Booking Payment Initiated | A payment attempt is initiated (before confirmation). |
| Booking No-Show Updated | A host or attendee is marked as a no-show after the meeting. |
| Meeting Started | At the scheduled start time of the meeting. Uses a flat payload format. Automatically cancelled if the booking is cancelled or rescheduled. |
| Meeting Ended | At the scheduled end time of the meeting. Uses a flat payload format. Automatically cancelled if the booking is cancelled or rescheduled. |
| Recording Ready | A meeting recording is available and ready to access. |
| Recording Transcription Generated | A transcription of the meeting recording is successfully generated. |
| Instant Meeting Created | An instant (ad-hoc) meeting is created. |
| Instant Meeting Accepted | A host accepts an instant meeting and becomes the organizer. Only fires for the first host to accept. |
| Out of Office Created | A user adds a new Out of Office entry to their availability. |
| After Hosts Cal Video No-Show | The host did not show up to a Cal Video meeting in the first n minutes, as set up in the configuration. |
| After Guests Cal Video No-Show | The attendee did not show up to a Cal Video meeting in the first n minutes, as set up in the configuration. |
| Form Submitted | A form is submitted as part of a routing form with a scheduled event. |
| Form Submitted (No Event) | A form is submitted without a scheduled event (form-only flow). |
| Calendar Entry Rejected | An external attendee declines a Cal.com event from their connected Google or Microsoft 365 calendar. |
| Delegation Credential Rotation Required | The client secret for a Microsoft 365 Delegation Credential that has opted out of automatic rotation is approaching expiry (~14 days out). Organization-level only. |
For booking links with seats enabled, the attendees array in webhook payloads contains only the attendee associated with the specific seat that triggered the webhook. For example, when a new seat is booked, the webhook includes only that seat's attendee — not all attendees across the entire booking. This applies to all booking-related triggers (BOOKING_CREATED, BOOKING_RESCHEDULED, etc.).
Most webhook events use a nested payload format with booking details inside a payload object. The MEETING_STARTED and MEETING_ENDED events use a different flat format where booking fields are at the top level.
Events like BOOKING_CREATED, BOOKING_CANCELLED, BOOKING_RESCHEDULED, and most other triggers use this format:
{
"triggerEvent": "BOOKING_CREATED",
"createdAt": "2023-05-24T09:30:00.538Z",
"payload": {
"type": "60min",
"title": "60min between Pro Example and John Doe",
"description": "",
"additionalNotes": "",
"customInputs": {},
"startTime": "2023-05-25T09:30:00Z",
"endTime": "2023-05-25T10:30:00Z",
"organizer": {
"id": 5,
"name": "Pro Example",
"email": "owner@acme.com",
"username": "owner90",
"usernameInOrg": "owner",
"timeZone": "Asia/Kolkata",
"language": {
"locale": "en"
},
"timeFormat": "h:mma"
},
"responses": {
"name": {
"label": "your_name",
"value": "John Doe"
},
"email": {
"label": "email_address",
"value": "john.doe@example.com"
},
"location": {
"label": "location",
"value": {
"optionValue": "",
"value": "inPerson"
}
},
"notes": {
"label": "additional_notes"
},
"guests": {
"label": "additional_guests"
},
"rescheduleReason": {
"label": "reschedule_reason"
}
},
"userFieldsResponses": {},
"attendees": [
{
"email": "john.doe@example.com",
"name": "John Doe",
"timeZone": "Asia/Kolkata",
"language": {
"locale": "en"
}
}
],
"location": "Calcom HQ",
"destinationCalendar": {
"id": 10,
"integration": "apple_calendar",
"externalId": "https://caldav.icloud.com/1234567/calendars/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX/",
"userId": 5,
"eventTypeId": null,
"credentialId": 1
},
"hideCalendarNotes": false,
"requiresConfirmation": null,
"eventTypeId": 7,
"seatsShowAttendees": true,
"seatsPerTimeSlot": null,
"uid": "bFJeNb2uX8ANpT3JL5EfXw",
"appsStatus": [
{
"appName": "Apple Calendar",
"type": "apple_calendar",
"success": 1,
"failures": 0,
"errors": [],
"warnings": []
}
],
"eventTitle": "60min",
"eventDescription": "",
"price": 0,
"currency": "usd",
"length": 60,
"bookingId": 91,
"metadata": {},
"status": "ACCEPTED"
}
}MEETING_STARTED and MEETING_ENDED webhooks use a flat payload format where booking fields are at the top level alongside triggerEvent, rather than nested inside a payload object. These webhooks are delivered at the scheduled start and end time of the meeting respectively.
{
"triggerEvent": "MEETING_STARTED",
"id": 91,
"uid": "bFJeNb2uX8ANpT3JL5EfXw",
"title": "60min between Pro Example and John Doe",
"description": "",
"startTime": "2023-05-25T09:30:00.000Z",
"endTime": "2023-05-25T10:30:00.000Z",
"location": "https://cal.app/video/abc123",
"status": "ACCEPTED",
"paid": false,
"createdAt": "2023-05-24T09:30:00.538Z",
"updatedAt": "2023-05-24T09:30:00.538Z",
"userId": 5,
"eventTypeId": 7,
"metadata": {},
"responses": {
"name": {
"label": "your_name",
"value": "John Doe"
},
"email": {
"label": "email_address",
"value": "john.doe@example.com"
}
},
"user": {
"email": "owner@acme.com",
"name": "Pro Example",
"username": "owner90",
"timeZone": "Asia/Kolkata",
"locale": "en"
},
"attendees": [
{
"id": 201,
"name": "John Doe",
"email": "john.doe@example.com",
"timeZone": "Asia/Kolkata",
"locale": "en",
"noShow": false
}
],
"payment": [],
"references": [
{
"id": 42,
"type": "daily_video",
"uid": "abc123",
"meetingId": "abc123",
"meetingUrl": "https://cal.app/video/abc123"
}
]
}If a booking is cancelled or rescheduled before the meeting time, the scheduled MEETING_STARTED and MEETING_ENDED webhooks for that booking are automatically cancelled.
The INSTANT_MEETING webhook fires when a booker submits an Instant Meeting request. Its payload carries the booker's form responses and the connectAndJoinUrl a host opens to accept and join the meeting, so a receiving service can alert the hosts who can take the request.
The fields in responses depend on the booking questions configured on the booking link, so your own payload can contain more or fewer fields than the example below. customInputs is empty unless the booking link still uses legacy custom inputs.
{
"triggerEvent": "INSTANT_MEETING",
"createdAt": "2025-04-17T10:00:00.000Z",
"payload": {
"triggerEvent": "INSTANT_MEETING",
"uid": "aB3kL9mNpQ7rS1tU",
"responses": {
"name": "Jane Smith",
"email": "jane.smith@example.com",
"notes": "Need help choosing a plan",
"guests": []
},
"connectAndJoinUrl": "https://app.cal.com/connect-and-join?token=EXAMPLE_TOKEN",
"eventTypeId": 15,
"eventTypeTitle": "Instant meeting",
"customInputs": {}
}
}The INSTANT_MEETING_ACCEPTED webhook fires when a host accepts an instant meeting request through the connect-and-join flow. It only triggers for the first host to accept — if another host has already accepted the booking, the webhook is not sent again. This trigger is available for team booking links only.
The payload includes the booking status (set to ACCEPTED), the accepting host as the organizer with their locale and time format preferences, the guest attendees list, booking responses, and a metadata object containing the videoCallUrl for the meeting.
{
"triggerEvent": "INSTANT_MEETING_ACCEPTED",
"createdAt": "2025-04-17T10:01:00.000Z",
"payload": {
"bookingId": 142,
"bookingUid": "aB3kL9mNpQ7rS1tU",
"eventTypeId": 15,
"status": "ACCEPTED",
"title": "Instant meeting between Team and Jane Smith",
"startTime": "2025-04-17T10:00:00.000Z",
"endTime": "2025-04-17T10:30:00.000Z",
"organizer": {
"id": 8,
"name": "Host Example",
"email": "host@example.com",
"username": "host-example",
"timeZone": "America/New_York",
"language": {
"locale": "en"
},
"timeFormat": "h:mma",
"utcOffset": -300
},
"attendees": [
{
"email": "jane.smith@example.com",
"name": "Jane Smith",
"timeZone": "Europe/London",
"language": {
"locale": "en"
},
"utcOffset": 60
}
],
"responses": {
"name": {
"label": "your_name",
"value": "Jane Smith"
},
"email": {
"label": "email_address",
"value": "jane.smith@example.com"
}
},
"location": "integrations:daily",
"metadata": {
"videoCallUrl": "https://cal.app/video/aB3kL9mNpQ7rS1tU"
}
}
}The CALENDAR_ENTRY_REJECTED webhook fires when an external attendee declines a Cal.com event from their connected Google Calendar or Microsoft 365 calendar. Cal.com detects the decline during calendar sync and dispatches the webhook once per attendee per booking — duplicate syncs do not re-fire the trigger, so you can rely on it as an at-most-once signal.
Use this trigger when you want to react to attendee declines that happen outside Cal.com, for example to notify the host, update a CRM, or offer the attendee a reschedule link. The webhook resolves subscribers at the user, booking link, team, and organization levels, so any matching subscription receives the payload.
The payload uses a flat format with booking, calendarEvent, and declinedAttendee objects at the top level:
{
"triggerEvent": "CALENDAR_ENTRY_REJECTED",
"createdAt": "2026-06-18T14:22:00.000Z",
"booking": {
"uid": "aB3kL9mNpQ7rS1tU",
"title": "60min between Pro Example and Jane Smith",
"startTime": "2026-06-20T09:30:00.000Z",
"endTime": "2026-06-20T10:30:00.000Z"
},
"calendarEvent": {
"id": "abc123xyz",
"iCalUID": "abc123xyz@google.com",
"provider": "google_calendar"
},
"declinedAttendee": {
"email": "jane.smith@example.com"
}
}The provider field is google_calendar or office365_calendar depending on where the decline originated.
Cal.com validates webhook subscriber URLs to protect against server-side request forgery (SSRF). The validation rules depend on whether you are using Cal.com Cloud or a self-hosted instance.
Cal.com Cloud:
- The subscriber URL must use HTTPS.
- URLs pointing to private or internal IP addresses (such as
10.x.x.x,172.16.x.x,192.168.x.x, or127.0.0.1) are blocked. - Cloud metadata endpoints (such as
169.254.169.254) are blocked. - Hostnames that resolve to private IP addresses via DNS are also blocked.
Self-hosted:
- Both HTTP and HTTPS URLs are accepted, so you can use internal services as webhook targets.
- Private IP addresses are allowed for internal webhooks.
- Cloud metadata endpoints are still blocked for security, since self-hosted instances may run on cloud infrastructure.
-
Simply add a new secret key to your webhook and save.
-
Wait for the webhook to be triggered (event created, cancelled, rescheduled, or meeting ended)
-
Use the secret key to create an
hmac, and update that with the webhook payload received to create an SHA256. -
Compare the hash received in the header of the webhook
(X-Cal-Signature-256)with the one created using the secret key and the body of the payload. If they don't match, the received payload was adulterated and cannot be trusted.
If your endpoint expects its own authentication or routing headers, you can add them to the webhook. Cal.com sends them with every delivery, along with the standard Cal.com headers.
-
Open the webhook in Settings → Developer → Webhooks, or create a new one.
-
In Custom headers, click Add header.
-
Enter the Header name and Header value. For example,
Authorizationwith the valueBearer your-token. -
Add more headers if you need them, then save the webhook.
Things to know:
- You can add up to 10 headers per webhook.
- Header values are stored encrypted. After you save, values are masked and can't be read back, so keep a copy of them elsewhere.
- If you change the Subscriber URL, saved header values aren't sent to the new URL. Enter them again before you save.
- Header names that start with
X-Cal-are reserved for Cal.com, and connection headers such asHost,Content-Length,ConnectionandTransfer-Encodingcan't be set. - Each value can be up to 4 KB and can't contain line breaks.
- Custom headers don't replace the secret. If you set a secret, the
X-Cal-Signature-256header is still sent so you can verify the payload.
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:
{
"content": "A new event has been scheduled",
"type": "{{type}}",
"name": "{{title}}",
"organizer": "{{organizer.name}}",
"booker": "{{attendees.0.name}}"
}where {{type}} represents the booking link slug and {{title}} represents the title of the booking link. 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:
| 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, INSTANT_MEETING, INSTANT_MEETING_ACCEPTED, FORM_SUBMITTED, CALENDAR_ENTRY_REJECTED] |
| createdAt | Datetime | The Time of the webhook |
| type | String | The booking link slug |
| title | String | The booking link 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 booking link settings |
| location | String | Location of the event |
| organizer | Organizer | The organizer of the event |
| attendees | Attendee[] | The event booker & any guests. For seated booking links, this contains only the attendee for the specific seat that triggered the webhook. |
| 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 a metadata of the booking, including the meeting URL (videoCallUrl) in case of Google Meet and Cal Video |
| Variable | Type | Description |
|---|---|---|
| name | String | Name of the organizer |
| Email of the organizer | ||
| username | String | Global username of the organizer |
| usernameInOrg | String | Username of the organizer within their organization (if applicable) |
| timeZone | String | Timezone of the organizer ("America/New_York", "Asia/Kolkata", etc.) |
| language?.locale | String | Locale of the organizer ("en", "fr", etc.) |
| Variable | Type | Description |
|---|---|---|
| name | String | Name of the attendee |
| Email of the attendee | ||
| timeZone | String | Timezone of the attendee ("America/New_York", "Asia/Kolkata", etc.) |
| language?.locale | String | Locale of the attendee ("en", "fr", etc.) |