[TortoiseWolfe]

The webhook half of Phase 3b. An earlier pass in this same session concluded it could not be
built on Cal.com. That was wrong, and the correction is measured rather than argued: utm_content
really does not survive, but a hidden custom booking field does — and that is a carrier we
control.

The loop, driven end to end on production before this was committed

click "Book a call"   →  create-lead returns an id
/schedule?lead=ID     →  embed prefills the hidden `lead_ref` booking field
visitor books         →  Cal.com POSTs BOOKING_CREATED
calcom-webhook        →  the lead advances to `scheduled`

The row afterwards:

status        scheduled
name          End To End
email         admin@scripthammer.com
scheduled_at  2026-09-14 13:00:00+00
booking_ref   cp8JzQ2am3bJPVgnUcN8S5

webhook_events:  provider=calcom  signature_verified=true  processed=true

The signature is measured, not documented

A live delivery carries x-cal-signature-256 with 64 hex characters and no prefix.

That matters more than usual: agents/skills/calcom-api/references/webhooks.md inside Cal.com's
own repository compares against `sha256=${expected}` — which would reject 100% of real
deliveries — and it is the document an agent researching this problem is most likely to find. A test
pins the bare form specifically so nobody "fixes" this to match it.

Five rejection paths, all driven live

sent	answer
no signature header	400
the literal no-secret-provided	400
a prefixed sha256= signature	400
valid signature over a tampered body	400
correctly signed replay	200 {handled:false, "already processed"}

The second is the sharpest trap in this integration. A webhook configured without a secret still
sends the header, valued no-secret-provided — so a receiver written if (!sig) return 401 sees a
present, non-empty string and accepts unsigned traffic. The literal is rejected by name.

A booking with no lead_ref is not an error. Somebody can always book from a Cal.com link that
never touched this site, and answering that with a 4xx would make the operator's webhook log red for
people booking calls correctly. It is recorded, acknowledged 200, and never retried.

The CTA now awaits, and that is the feature

The id only exists in create-lead's response, so fire-and-forget cannot carry it. The wait is
capped at 1200ms and every failure — slow, offline, rate-limited, unconfigured — falls through to
the plain navigation. Worst case is an unattributed booking, which is what happened for every booking
before this existed. It stays a real <a href> underneath, so no-JS and middle-click still reach the
calendar.

Schema

T036 widens webhook_events.provider to accept both schedulers, not just the one this deployment
runs — calendar.config.ts supports Calendly by design and a fork may be on it. DROP+ADD, and
applied to production: an inline edit to the CREATE TABLE is a silent no-op on a provisioned
database. The other three provider CHECKs are deliberately left alone; they already disagree with
each other and harmonising them is a separate decision.

Live outside the repo

The hidden lead_ref field on both bookable event types, and the BOOKING_CREATED webhook pointing at
calcom-webhook (v1, ACTIVE, verify_jwt: false). CALCOM_WEBHOOK_SECRET is documented in
.env.example including why leaving it unset fails closed. All test data was removed afterwards —
booking cancelled, lead and ledger rows deleted.

5,831 unit tests, 961 script tests, deno check clean across 18 functions.

Closes #562.

🤖 Generated with Claude Code