Skip to content
Help center
Developers

Receive and verify booking events

Subscribe to events and verify each request before your server processes it.

Subscribe to events and verify each request before your server processes it.

  1. Add endpoint
  2. Store the secret
  3. Event arrives
  4. Verify, then process

You need the Pro plan or higher, and a public HTTPS address (your "receiver") that accepts requests. Owners and admins can set this up. Other roles need the Calendaty AI → Modify AI settings permission.

Open Custom Webhooks

Open Manage Integrations. Scroll to API & Webhooks.

Choose Setup Custom Webhooks.

  1. Setup Custom Webhooks
API and Webhooks section with the Custom Webhooks card and Calendaty API marked Coming soon

Add the endpoint

Choose Add endpoint.

Enter the Endpoint URL. This is the HTTPS address of your receiver.

Choose one or more Events, then choose Create endpoint.

  1. Endpoint URL
  2. Events
  3. Create endpoint
Add webhook endpoint dialog with the Endpoint URL field, the Events list and the Create endpoint button

Store the signing inputs

A window called Your signing secret opens. Choose Copy and keep the secret on your server. It is shown only once.

Your server also needs the Organization ID and the endpoint ID. They are part of the signature, but the dashboard does not show them.

  • The endpoint ID is the id in the create response and in GET /cosmo/webhooks.
  • The Organization ID is session.activeOrganizationId in GET /api/auth/get-session.

Both calls need a signed-in session. If you cannot read them, contact us.

Verify before processing

Read the raw request body bytes. Apply the verification example before you parse or process an event.

Test your receiver

Choose Test on the endpoint. It sends test/ping.

Check your receiver's result. Then test a real workflow for each event you use.

  1. Test
Custom Webhooks with a demo HTTPS endpoint, its events, the enabled switch and the Test button

Event catalog

AreaEvents
Bookingbooking/created, booking/cancelled, booking/rescheduled, booking/completed, booking/reminder
Holdhold/created, hold/expiring, hold/expired
Paymentpayment/received, payment/refunded
Customercustomer/created, customer/milestone
Leadlead/qualified, lead/converted
Chatchat/escalated, chat/resolved

There are 16 events. test/ping is a test event. You cannot subscribe to it.

The dashboard lists 11 of them. To subscribe to booking/reminder, hold/created, hold/expiring, hold/expired or customer/milestone, use the PATCH /cosmo/webhooks/:id route below.

Body and headers

The JSON envelope has event, timestamp, and payload. The timestamp is an ISO date string.

{
  "event": "test/ping",
  "timestamp": "2026-09-27T12:00:00.000Z",
  "payload": {
    "message": "Calendaty webhook test delivery"
  }
}

The request includes:

  • Content-Type: application/json
  • x-calendaty-signature
  • x-calendaty-timestamp
  • x-calendaty-event

The signature is lowercase hexadecimal without a sha256= prefix. Use the entire secret, including whsec_, as the HMAC key.

bodyHash = SHA256_HEX(rawBody)
message = timestamp + "." + organizationId + "." + endpointId + "." + bodyHash
signature = HMAC_SHA256_HEX(secret, message)

Use the timestamp header in the signed message. Load the Organization ID and endpoint ID from trusted receiver configuration, not from unverified request data.

Verification example

This Node.js example checks a five-minute freshness window. It compares signatures in constant time. Your receiver enforces the window; delivery does not enforce it for you.

Pass a Buffer with the original body bytes. Do not parse and reserialize JSON before verification.

import { createHash, createHmac, timingSafeEqual } from 'node:crypto'

export function verifyWebhook({
  rawBody,
  signature,
  timestamp,
  secret,
  organizationId,
  endpointId,
  now = Date.now(),
}) {
  if (
    !Buffer.isBuffer(rawBody) ||
    typeof signature !== 'string' ||
    !/^[a-f0-9]{64}$/.test(signature) ||
    typeof timestamp !== 'string' ||
    !secret ||
    !organizationId ||
    !endpointId
  ) {
    return false
  }

  const sentAt = Date.parse(timestamp)
  if (!Number.isFinite(sentAt) || Math.abs(now - sentAt) > 300_000) {
    return false
  }

  const bodyHash = createHash('sha256').update(rawBody).digest('hex')
  const message = `${timestamp}.${organizationId}.${endpointId}.${bodyHash}`
  const expected = createHmac('sha256', secret).update(message).digest()

  return timingSafeEqual(expected, Buffer.from(signature, 'hex'))
}

Do

Reject invalid requests before doing any work. Then parse and validate the event and payload.

Don't

Route by x-calendaty-event without first checking it matches the signed body's event.

Delivery and retries

  1. Try 1
  2. Wait 1, 5, 15, 60 min
  3. Up to 5 tries
  4. dead_letter

Any 2xx response succeeds. The timeout is 10 seconds. The response-size limit is 16,384 bytes, so keep your response small.

Persist accepted work before you return 2xx. Then process it separately if needed.

Each attempt gets a new timestamp and signature. Design handlers so repeated events cannot repeat a harmful action. There is no exactly-once guarantee.

More details