Skip to content

API Reference

Webhooks

Receive real-time notifications when events occur in your business.

Overview

Webhooks let you receive HTTP POST notifications when events happen in your Calendence business — new bookings, cancellations, payment updates, and more. Growth Pro

Managing Webhooks

Register a Webhook

POST /api/v1/webhooks

Requires a business or hub API key.

curl -X POST https://calendence.com/api/v1/webhooks \
  -H "Authorization: Bearer cal_biz_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhooks/calendence",
    "events": ["booking.created", "booking.cancelled"]
  }'

List Webhooks

GET /api/v1/webhooks

Delete a Webhook

DELETE /api/v1/webhooks/{id}

Event Types

Event Trigger
booking.created A new booking is confirmed
booking.updated A booking is rescheduled or modified
booking.cancelled A booking is cancelled
booking.completed A booking is marked as completed

Payload Format

All webhook payloads follow the same structure:

{
  "event": "booking.created",
  "timestamp": "2026-03-24T14:30:00+00:00",
  "data": {
    "id": "booking-uuid",
    "status": "confirmed",
    "service": {
      "id": "service-uuid",
      "name": "Express Wash"
    },
    "client": {
      "first_name": "Jane",
      "last_name": "Doe",
      "email": "jane@example.com"
    },
    "starts_at": "2026-03-25T14:00:00+00:00",
    "ends_at": "2026-03-25T14:30:00+00:00",
    "location": {
      "id": "location-uuid",
      "name": "Main Shop"
    }
  }
}

Delivery

  • Webhooks are delivered via HTTP POST with a JSON body
  • Content-Type: application/json
  • Timeout: 10 seconds per delivery attempt
  • Retries: 3 attempts with exponential backoff
  • If all retries fail, the webhook is marked as failed in the delivery log

Security

Verify webhook authenticity by checking the signature header:

X-Calendence-Signature: sha256=abc123...

The signature is an HMAC-SHA256 hash of the request body using your webhook secret. Verify it server-side:

$payload = file_get_contents('php://input');
$signature = hash_hmac('sha256', $payload, $webhookSecret);
$valid = hash_equals($signature, $request->header('X-Calendence-Signature'));

Best Practices

  • Always respond with 200 — Return a 200 status quickly, then process the webhook asynchronously
  • Handle duplicates — Webhooks may be delivered more than once. Use the event ID for deduplication
  • Verify signatures — Always validate the HMAC signature before processing
  • Use HTTPS — Webhook URLs must use HTTPS in production