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.
- Add endpoint
- Store the secret
- Event arrives
- 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.
- Setup Custom Webhooks
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.
- Endpoint URL
- Events
- Create endpoint
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
idin the create response and inGET /cosmo/webhooks. - The Organization ID is
session.activeOrganizationIdinGET /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.
- Test
Event catalog
| Area | Events |
|---|---|
| Booking | booking/created, booking/cancelled, booking/rescheduled, booking/completed, booking/reminder |
| Hold | hold/created, hold/expiring, hold/expired |
| Payment | payment/received, payment/refunded |
| Customer | customer/created, customer/milestone |
| Lead | lead/qualified, lead/converted |
| Chat | chat/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/jsonx-calendaty-signaturex-calendaty-timestampx-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
- Try 1
- Wait 1, 5, 15, 60 min
- Up to 5 tries
- 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.