Skip to content

Latest commit

 

History

History
244 lines (203 loc) · 16.9 KB

webhooks.mdx

File metadata and controls

244 lines (203 loc) · 16.9 KB
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.

Webhook scope levels

Webhooks can be created at multiple levels of scope, each determining which events they apply to:

  • User-level: Triggers for all event types owned by the user (excluding team-managed types).

  • Event-type level: Triggers only for a specific event type. Useful for fine-grained control.

  • Team-level: Applies to team event types (i.e., Collective and Round Robin) within the specified team.

    In the case of Managed events, bookings are made on the child event types, not the parent team event. Because of this, team-level webhooks will **not** trigger for managed events unless one of the following is true:
    • You create a webhook directly on the parent event type (recommended), or
    • You create individual webhooks on the child event types (owned by users).

    💡 Note: Users can create webhooks that apply to their own event types, including child events under a managed event, even if a team-level webhook exists.

  • Organization-level: Applies to all team event types across all teams within the organization.

Creating a webhook subscription

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

  1. Subscriber URL: The listener URL where the payload will be sent to, when an event trigger is triggered.

  2. 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, Out of Office Created, After Hosts Cal Video No-Show, After Guests Cal Video No-Show, Form Submitted, and Form Submitted (No Event).

  3. 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.

  4. Custom Payload: You have the option to customize the payload you receive when a subscribed event is triggered.

Expectations with the triggers

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.
Meeting Ended At the scheduled end time of the meeting.
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.
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).

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": "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"
    }
}

Verifying the authenticity of the received payload

  1. Simply add a new secret key to your webhook and save.

  2. Wait for the webhook to be triggered (event created, cancelled, rescheduled, or meeting ended)

  3. Use the secret key to create an hmac, and update that with the webhook payload received to create an SHA256.

  4. 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.

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

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 Organizer The organizer of the event
attendees Attendee[] 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 a metadata of the booking, including the meeting URL (videoCallUrl) in case of Google Meet and Cal Video

Organizer Structure

Variable Type Description
name String Name of the organizer
email Email 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.)

Attendee Structure

Variable Type Description
name String Name of the attendee
email Email 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.)