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

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.

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

{
    "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": "[email protected]",
            "username": "pro",
            "timeZone": "Asia/Kolkata",
            "language": {
                "locale": "en"
            },
            "timeFormat": "h:mma"
        },
        "responses": {
            "name": {
                "label": "your_name",
                "value": "John Doe"
            },
            "email": {
                "label": "email_address",
                "value": "[email protected]"
            },
            "location": {
                "label": "location",
                "value": {
                    "optionValue": "",
                    "value": "inPerson"
                }
            },
            "notes": {
                "label": "additional_notes"
            },
            "guests": {
                "label": "additional_guests"
            },
            "rescheduleReason": {
                "label": "reschedule_reason"
            }
        },
        "userFieldsResponses": {},
        "attendees": [
            {
                "email": "[email protected]",
                "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"
    }
}

​
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:

{
  "content": "A new event has been scheduled",
  "type": "{{type}}",
  "name": "{{title}}",
  "organizer": "{{organizer.name}}",
  "booker": "{{attendees.0.name}}"
}

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

VariableTypeDescription
triggerEventStringThe 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]
createdAtDatetimeThe time of the webhook
typeStringThe event type slug
titleStringThe event type name
startTimeDatetimeThe event’s start time
endTimeDatetimeThe event’s end time
descriptionStringThe event’s description as described in the event type settings
locationStringLocation of the event
organizerPersonThe organizer of the event
attendeesPerson[]The event booker & any guests
uidStringThe UID of the booking
rescheduleUidStringThe UID for rescheduling
cancellationReasonStringReason for cancellation
rejectionReasonStringReason for rejection
team.nameStringName of the team booked
team.membersString[]Members of the team booked
metadataJSONContains metadata of the booking, including the meeting URL (videoCallUrl) in case of Google Meet and Cal Video

​
Person Structure

VariableTypeDescription
nameStringName of the individual
emailEmailEmail of the individual
timezoneStringTimezone of the individual (e.g., “America/New_York”, “Asia/Kolkata”)
language?.localeStringLocale of the individual (e.g., “en”, “fr”)

Was this page helpful?

SSO setupSetting up mailtrap for email testing