RonanCodes/cal-com

Cal.com integration

Add real scheduling + video to an app. The booker picks a slot, Cal.com generates a Cal Video (Daily) room automatically, and a webhook syncs the booking + join link into your DB.

THE #1 GOTCHA: cal.com vs cal.eu

Cal.com has separate cloud instances with separate API hosts. If the account is on the EU instance (cal.eu/<username>), the API base is https://api.cal.eu/v2, NOT api.cal.com. A key from a cal.eu account returns 401 Invalid API Key against api.cal.com. Always confirm the host first:

KEY="cal_live_..."
curl -s -H "Authorization: Bearer $KEY" -H "cal-api-version: 2024-08-13" https://api.cal.eu/v2/me
# falls back to https://api.cal.com/v2/me for US accounts

Store the base as an env var (CALCOM_API_BASE) so code isn't hardcoded to one region. API v1 is decommissioned (HTTP 410) — v2 only.

Auth + API versions

• Header Authorization: Bearer cal_live_... on every call.
• Header cal-api-version is per-endpoint and matters:
  • Event types create: 2024-06-14
  • Bookings / most reads: 2024-08-13
  • If the version is wrong the endpoint silently uses an older schema. When a response shape looks off, check the version header first.
• API key from the dashboard: Settings → Developer → API Keys (format cal_live_...).

Set up the whole flow programmatically (no dashboard clicking)

With just the API key you can create the event type AND the webhook, so the integration is self-provisioning.

1. Create a Cal Video event type:

curl -X POST "$CALCOM_API_BASE/event-types" \
  -H "Authorization: Bearer $CALCOM_API_KEY" -H "cal-api-version: 2024-06-14" \
  -H "Content-Type: application/json" \
  -d '{"lengthInMinutes":30,"title":"Property viewing","slug":"property-viewing",
       "locations":[{"type":"integration","integration":"cal-video"}]}'

The booking link is then <instance>/<username>/<slug> (e.g. cal.eu/ronanconnolly/property-viewing); the embed calLink is <username>/<slug>. Cal Video is installed by default; the location above makes every booking generate a unique room.

2. Create the webhook (you choose the secret):

curl -X POST "$CALCOM_API_BASE/webhooks" \
  -H "Authorization: Bearer $CALCOM_API_KEY" -H "cal-api-version: 2024-08-13" \
  -H "Content-Type: application/json" \
  -d '{"subscriberUrl":"https://<app>/api/calcom/webhook","active":true,
       "triggers":["BOOKING_CREATED","BOOKING_CANCELLED"],"secret":"whsec_..."}'

Triggers enum includes: BOOKING_CREATED, BOOKING_CANCELLED, BOOKING_RESCHEDULED, BOOKING_REQUESTED, MEETING_ENDED, RECORDING_READY, and more. Set the event type to auto-confirm (no requiresConfirmation) so the Cal Video link is present on the first BOOKING_CREATED.

The embed (recommended UI path)

npm i @calcom/embed-react. No API key needed client-side — just the public calLink. Mark "use client" in Next App Router. Prefill from your session, restyle to brand:

"use client";
import Cal, { getCalApi } from "@calcom/embed-react";
import { useEffect } from "react";
export function BookViewing({ name, email }: { name: string; email: string }) {
  useEffect(() => { (async () => {
    const cal = await getCalApi();
    cal("ui", { styles: { branding: { brandColor: "#7c3aed" } }, layout: "month_view" });
  })(); }, []);
  return <Cal calLink={process.env.NEXT_PUBLIC_CALCOM_LINK!}
    config={{ name, email, layout: "month_view" }} style={{ width: "100%", height: 640 }} />;
}

React 19 / Next 16 peer-dep friction is common — install with --legacy-peer-deps if npm i complains, and pin the latest @calcom/embed-react.

Booking → DB webhook (signature-verified)

Read the raw body (HMAC-SHA256 over the raw bytes with your secret; header x-cal-signature-256). In Next App Router:

import crypto from "node:crypto";
export async function POST(req: Request) {
  const raw = await req.text();                         // raw, not parsed JSON
  const sig = req.headers.get("x-cal-signature-256") ?? "";
  const expected = crypto.createHmac("sha256", process.env.CALCOM_WEBHOOK_SECRET!)
    .update(raw).digest("hex");
  if (!sig || !crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected)))
    return new Response("invalid signature", { status: 401 });
  const { triggerEvent, payload } = JSON.parse(raw);
  // payload.uid, payload.startTime, payload.endTime, payload.attendees[0].email,
  // payload.videoCallData?.url  <-- the Cal Video join link
  // upsert into your bookings/viewings table here
  return new Response("ok");
}

payload.videoCallData.url is the join link (also in Cal's own confirmation email). Store it and render a "Join" button. If the event requires manual confirmation the link can be absent on the first event — auto-confirm avoids it.

Env vars (convention)

CALCOM_API_KEY=cal_live_...
CALCOM_API_BASE=https://api.cal.eu/v2     # or api.cal.com for US
CALCOM_WEBHOOK_SECRET=whsec_...
NEXT_PUBLIC_CALCOM_LINK=<username>/<event-slug>   # public, for the embed

Checklist

• [ ] Confirm the instance host (cal.eu vs cal.com) with a /v2/me call before anything else.
• [ ] Right cal-api-version per endpoint (event-types 2024-06-14, bookings 2024-08-13).
• [ ] Event type created with Cal Video location + auto-confirm.
• [ ] Webhook created (BOOKING_CREATED + CANCELLED) with a secret you store.
• [ ] Embed prefilled + brand-coloured; install with legacy-peer-deps on React 19.
• [ ] Webhook route verifies the raw-body HMAC and stores videoCallData.url.

Further reading

• API v2 reference: https://cal.com/docs/api-reference/v2/introduction
• Webhooks: https://cal.com/docs/developing/guides/automation/webhooks
• Embed: https://www.npmjs.com/package/@calcom/embed-react
• Cal Video: https://cal.com/features/cal-video