cal-com

cal-com with GTM OS

When to use this skill

Use when processing a Cal.com booking webhook as a GTM discovery-call signal.

What GTM OS uses it for

Inbound webhook adapter that verifies Cal.com booking events; it is not a general scheduling write API.

Capabilities and operation names are listed below as they appear in the connector package and coverage map. Discover the live input and output schema with gtm describe before invocation; the registry for the current organization is authoritative if it differs from this static guide.

• cal_com.ingest_booking_webhook verifies the inbound booking webhook.
• The package maps supported booking data to gtm.contact, gtm.account, and gtm.signal; the declared event is discovery_call_booked.

Connect it

Configure a per-org inbound webhook signing secret in the sealed cal_com connection. The webhook endpoint is configured in the GTM OS deployment; no Cal.com API key is required for signature verification. Use the console connection/settings flow to rotate the secret.

Webhook verification uses an HMAC signing secret, not OAuth scopes. Configure the matching Cal.com webhook signing secret on both ends without exposing it in logs or chat.

Use the console Connections/settings page for the provider when present. For CLI setup, inspect gtm connect --help and use the provider name supported by the installed CLI; do not guess flags or paste credentials into command history. Restart/reload the configured instance only through its documented operator workflow.

Canonical data

• Booking identity can resolve or create gtm.contact / gtm.account per the ingest mapping.
• Emits gtm.signal for discovery_call_booked.
• Don't infer attendance or qualification from a booking event alone.

Read and write records through registered operations and gtm.* objects only. A vendor-side record is not automatically a canonical GTM OS record; use the connector's declared mapping and retain source provenance. Do not infer fields from the vendor API.

Governance and safety

Inbound verification is not consent to market. Respect existing suppression and opt-outs before follow-up. Any outbound follow-up remains a separate approval-gated operation; do not auto-send from the webhook handler.

• E-class/customer-facing writes are proposed for approval; a different human approves them.
• Respect consent, suppression, unsubscribe, and do-not-contact state before any person-level action.
• Honor configured spend/budget caps. Do not retry a billable request blindly after timeout.
• Keep connection secrets in the sealed connection or server environment. Never print or commit them.

Common errors and recovery

• Signature mismatch: check raw request body, signing secret, and endpoint configuration.

• Duplicate delivery: rely on idempotent ingest behavior; don't create a second record manually.

• Missing attendee fields: preserve the event and report missing values; don't guess identity.

• Invalid event kind: inspect the supported webhook contract.

• Check the connection state and provider health before retrying; use the connector's fixture mode only for development.

• Read the operation error and lineage/receipt before changing inputs or repeating a write.

• If the provider is not registered, stop and report that limitation; do not call the vendor directly as a workaround.

Do

• Read the connector entry in docs/gtmos/reference/connections.md and the current gtm describe schema before a new integration action.
• Start with a read or one narrowly scoped test, confirm provenance, then scale within the approved budget.
• Ask a human to resolve missing consent, expired credentials, or approval-required actions.

Don't

• Don't invent endpoints, scopes, operation names, or object fields.
• Don't bypass GTM OS governance with direct vendor writes or direct database edits.
• Don't send messages, change campaigns, or publish content without the operation's approval path.

Official vendor documentation

https://cal.com/docs

GTM OS reference: docs/gtmos/reference/connections.md (installed by gtm init) and the live gtm describe schema.