Cal ID Webhooks

Webhooks let you automate downstream flows the moment something happens in Cal ID — a booking is scheduled, rescheduled, cancelled, paid for, and more. You subscribe to specific trigger events by pointing Cal ID at a subscriber URL that receives a JSON payload each time a trigger fires. Webhooks can be attached to your account or to individual event types, including team event types.

Prefer no-code? You can trigger automations without building a listener by connecting Cal ID to your other apps through an automation platform. For the full payload schemas and delivery details, see the Webhook events reference.

Available triggers

Trigger	Code	Fires when
Booking Created	`BOOKING_CREATED`	A booking is confirmed
Booking Requested	`BOOKING_REQUESTED`	A booking needs your confirmation
Booking Rescheduled	`BOOKING_RESCHEDULED`	An existing booking is moved
Booking Cancelled	`BOOKING_CANCELLED`	A booking is cancelled
Booking Rejected	`BOOKING_REJECTED`	You decline a requested booking
Booking Payment Initiated	`BOOKING_PAYMENT_INITIATED`	Checkout begins for a paid booking
Booking Paid	`BOOKING_PAID`	Payment for a booking succeeds
Booking No-show Updated	`BOOKING_NO_SHOW_UPDATED`	An attendee is marked as a no-show
Form Submitted	`FORM_SUBMITTED`	A routing form is submitted
Out-of-office Created	`OOO_CREATED`	An out-of-office entry is created

Create a webhook subscription

Open webhook settings

Go to Settings → Developer → Webhooks and click + Create.

Enter the Subscriber URL

This is the listener URL that receives the payload whenever a subscribed trigger fires.

Choose your event triggers

Select which triggers to listen to from the list above.

Add a secret (optional)

Provide a secret key to verify incoming payloads on your subscriber URL — this confirms a payload is authentic and hasn’t been tampered with. Leave it blank to skip.

Customize the payload (optional)

Optionally tailor the payload you receive when a subscribed event fires (see custom payload templates below).

New webhook form with the Subscriber URL field, the event trigger checkboxes, and the optional secret key field — Pointing Cal ID at your listener

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": "pro@example.com",
      "username": "pro",
      "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": "Cal ID 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"
  }
}

Verify the authenticity of a payload

When you set a secret, Cal ID signs each request so you can confirm it genuinely came from Cal ID.

Add a secret key

Add a secret key to your webhook and save.

Wait for a trigger

Wait for the webhook to fire — a booking is created, cancelled, rescheduled, and so on.

Compute an HMAC over the raw body

Compute HMAC-SHA256 using your webhook secret as the key and the raw request body as the message, then render the digest as lowercase hex:

signature = HMAC_SHA256(webhookSecret, rawRequestBody).digest("hex")

It must be the raw body — the exact bytes Cal ID sent. If your framework parses JSON before your handler runs, re-serialising the object will not reproduce those bytes (key order, whitespace and number formatting can all differ) and every signature will fail. Capture the raw body first.

Compare in constant time

Compare your digest with the value in the X-Cal-Signature-256 header using a constant-time comparison — crypto.timingSafeEqual in Node, hmac.compare_digest in Python.Do not use ==. A normal string comparison returns as soon as it finds a difference, so how long it takes reveals how many leading bytes were correct, and an attacker can recover a valid signature one byte at a time.If the values don’t match, reject the delivery with 401 and do not process it.

Verifying a delivery in code

Both examples read the raw body, compute the digest, and compare in constant time.

const crypto = require("crypto");
const express = require("express");
const app = express();

// express.raw() keeps the body as a Buffer. express.json() would parse it,
// and the parsed-then-restringified bytes will NOT match what Cal ID signed.
app.post("/webhooks/cal-id",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const received = req.get("X-Cal-Signature-256") || "";
    const expected = crypto
      .createHmac("sha256", process.env.CAL_ID_WEBHOOK_SECRET)
      .update(req.body)              // req.body is the raw Buffer
      .digest("hex");

    const a = Buffer.from(received, "utf8");
    const b = Buffer.from(expected, "utf8");
    // timingSafeEqual throws if the lengths differ, so check that first.
    if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
      return res.status(401).send("Invalid signature");
    }

    // Acknowledge fast, then do the slow work out of band.
    res.status(200).send("OK");
    queue.enqueue(JSON.parse(req.body.toString("utf8")));
  });

import hashlib, hmac, os
from fastapi import FastAPI, Request, Response

app = FastAPI()
SECRET = os.environ["CAL_ID_WEBHOOK_SECRET"].encode()

@app.post("/webhooks/cal-id")
async def cal_id_webhook(request: Request):
    raw = await request.body()          # the exact bytes Cal ID sent
    received = request.headers.get("X-Cal-Signature-256", "")
    expected = hmac.new(SECRET, raw, hashlib.sha256).hexdigest()

    if not hmac.compare_digest(received, expected):
        return Response(status_code=401, content="Invalid signature")

    enqueue(await request.json())       # safe to parse now
    return Response(status_code=200, content="OK")

Deliveries without a secret configured arrive unsigned. If verification matters to you, set a secret on the subscription — an endpoint that accepts unsigned deliveries can be called by anyone who learns the URL.

Adding a custom payload template

Customizable webhooks are a great way to reduce development effort — in many cases they remove the need to build an additional integration service. Here’s an example custom payload template:

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

Here {{type}} represents the event type slug and {{title}} represents the title of the event type. Variables must be wrapped in double curly braces as shown above. The full set of supported variables is listed below.

Webhook variable list

Variable	Type	Description
triggerEvent	String	The name of the trigger event [`BOOKING_CREATED`, `BOOKING_REQUESTED`, `BOOKING_RESCHEDULED`, `BOOKING_CANCELLED`, `BOOKING_REJECTED`, `BOOKING_PAYMENT_INITIATED`, `BOOKING_PAID`, `BOOKING_NO_SHOW_UPDATED`, `FORM_SUBMITTED`, `OOO_CREATED`]
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 set 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 of the 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 the case of Google Meet.

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”)

Get started

Guides

Cal ID Webhooks

Available triggers

Create a webhook subscription

An example webhook payload

Verify the authenticity of a payload

Verifying a delivery in code

Adding a custom payload template

Webhook variable list

Person structure

More webhook guides

Webhook events reference

Build a webhook receiver

​Available triggers

​Create a webhook subscription

​An example webhook payload

​Verify the authenticity of a payload

​Verifying a delivery in code

​Adding a custom payload template

​Webhook variable list

​Person structure

​More webhook guides

Webhook events reference

Build a webhook receiver

Available triggers

Create a webhook subscription

An example webhook payload

Verify the authenticity of a payload

Verifying a delivery in code

Adding a custom payload template

Webhook variable list

Person structure

More webhook guides