Appointment Webhooks
Get notified when appointments are created, updated, cancelled or completed and when calendar windows change.
Showing instructions for Xebit VoiceCloud.Showing instructions for Xebit VoiceKit, on your own infrastructure. Switch with the selector at the top. Updated 22 October 2026.
Appointment webhooks notify your server when an appointment is created, updated, cancelled or completed, and when a calendar window is created or changed. Register endpoints under the Xebit VoiceCloud dashboard → Integrations → Webhooks → Add Endpointthe Xebit VoiceKit admin console → Integrations → Webhooks → Add Endpoint and pick the appointment events you want.
API writes do not fire webhooks
Appointment and slot events are not sent for changes made through the REST API. They fire only for changes that come from:
- the dashboard (Xebit VoiceCloud dashboardXebit VoiceKit admin console);
- the AI voice agent, for appointments booked during a call.
If you create or change appointments through the API and other systems need to know, notify them from your own code.
Events you can register
| Event | When it fires |
|---|---|
appointment.created | An appointment is booked in the dashboard or by the AI voice agent. |
appointment.updated | An appointment's details are changed in the dashboard. |
appointment.cancelled | An appointment is cancelled in the dashboard. |
appointment.completed | An appointment is marked completed in the dashboard. |
slot.created | A calendar window is created in the dashboard. |
slot.updated | A calendar window is changed in the dashboard. |
Event payloads
appointment.* events
All four appointment events share one shape.
{
"event_id": "evt_a1b2c3d4-...",
"event": "appointment.created",
"timestamp": "2026-05-26T10:00:00.000Z",
"appointment": {
"appointment_id": "appt_a1b2c3d4e5",
"appointment_type": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"appointment_type_name": "General Checkup",
"branch_id": "branch_uuid_here",
"date": "2026-06-15",
"start_time": "2026-06-15T04:00:00.000Z",
"session": "Morning",
"batch": "MA",
"token": null,
"patient_name": "Aadhi",
"parent_phone": "+919840XXXXXX",
"doctor_name": null,
"status": "confirmed",
"booked_via": "phone_call",
"booked_at": "2026-05-26T10:00:00.000Z"
}
}| Field | Description |
|---|---|
event_id | Unique identifier of this delivery. |
event | appointment.created, appointment.updated, appointment.cancelled or appointment.completed. |
timestamp | ISO 8601 UTC time the event was sent. |
appointment.appointment_id | Appointment identifier. |
appointment.appointment_type | Service UUID. |
appointment.appointment_type_name | Readable service name. |
appointment.branch_id | Branch UUID. |
appointment.date | Appointment date, YYYY-MM-DD. |
appointment.start_time | Full ISO 8601 UTC date and time of the appointment. |
appointment.session | Session name. |
appointment.batch | Batch label. |
appointment.token | Queue token, if one was assigned. |
appointment.patient_name | Patient name. |
appointment.parent_phone | Patient phone number. |
appointment.doctor_name | Assigned doctor, if set. |
appointment.status | Current status. |
appointment.booked_via | How it was created: "phone_call" for the AI agent, "dashboard" for manual entry. |
appointment.booked_at | ISO 8601 UTC time the appointment was created. |
slot.* events
Both slot events share one shape.
{
"event_id": "evt_a1b2c3d4-...",
"event": "slot.updated",
"timestamp": "2026-05-26T10:00:00.000Z",
"slot": {
"slot_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890||2026-06-15",
"branch_id": "branch_uuid_here",
"appointment_type_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"appointment_type_name": "General Checkup",
"date": "2026-06-15",
"day_of_week": "monday",
"session": "Morning",
"batch": "MA",
"start_time": "09:00",
"end_time": "11:00",
"max_slots": 20,
"filled_slots": 3,
"available_slots": 17,
"status": "OPEN"
}
}Verifying signatures
When require_signature is true, each delivery carries two headers:
| Header | Description |
|---|---|
X-Webhook-Timestamp | Unix time in seconds when the payload was signed. |
X-Webhook-Signature | v1=<base64-encoded HMAC-SHA256>. |
The signature is HMAC-SHA256(secret, "{timestamp}.{rawBody}"), Base64 encoded (not hex) and prefixed with v1=, the same scheme as call webhooks.
# Send a signed test delivery to your own endpoint
SECRET="YOUR_WEBHOOK_SECRET"
TIMESTAMP=$(date +%s)
PAYLOAD='{"event_id":"evt_test","event":"appointment.created","timestamp":"2026-06-01T10:00:00.000Z","appointment":{"appointment_id":"appt_test"}}'
SIG="v1=$(printf '%s.%s' "$TIMESTAMP" "$PAYLOAD" | openssl dgst -sha256 -hmac "$SECRET" -binary | base64)"
curl -X POST https://your-server.example.com/webhook \
-H "Content-Type: application/json" \
-H "X-Webhook-Timestamp: $TIMESTAMP" \
-H "X-Webhook-Signature: $SIG" \
-d "$PAYLOAD"import base64
import hashlib
import hmac
def verify_signature(timestamp: str, raw_body: str, signature: str, secret: str) -> bool:
payload = f"{timestamp}.{raw_body}".encode()
expected = "v1=" + base64.b64encode(
hmac.new(secret.encode(), payload, hashlib.sha256).digest()
).decode()
# constant time, and safe when the lengths differ
return hmac.compare_digest(signature, expected)const crypto = require("crypto");
function verifySignature(secret, timestamp, rawBody, signatureHeader) {
const expected = "v1=" + crypto
.createHmac("sha256", secret)
.update(`${timestamp}.${rawBody}`)
.digest("base64");
const expectedBuf = Buffer.from(expected);
const actualBuf = Buffer.from(signatureHeader || "");
// timingSafeEqual throws on different lengths, so check first
if (expectedBuf.length !== actualBuf.length) return false;
return crypto.timingSafeEqual(expectedBuf, actualBuf);
}
// In a fetch-style handler (header names arrive in lower case)
const timestamp = request.headers.get("x-webhook-timestamp");
const signature = request.headers.get("x-webhook-signature");
const rawBody = await request.text(); // raw text, before any JSON.parse
if (!verifySignature(process.env.XEBIT_WEBHOOK_SECRET, timestamp, rawBody, signature)) {
return new Response("Invalid signature", { status: 401 });
}
const payload = JSON.parse(rawBody);Always compare with a constant time function such as hmac.compare_digest or crypto.timingSafeEqual, and reject payloads whose timestamp is more than a few minutes old.
Delivery and retries
Deliveries time out after 8 seconds and need a 2xx response to count as successful. A failed delivery is retried up to 5 times with exponential backoff:
| Attempt | Delay |
|---|---|
| 1 | Immediate |
| 2 | 30 seconds |
| 3 | 2 minutes |
| 4 | 10 minutes |
| 5 | 1 hour |
After 50 consecutive failures the webhook is switched off automatically. Turn it back on under the Xebit VoiceCloud dashboard → Integrations → Webhooksthe Xebit VoiceKit admin console → Integrations → Webhooks.
To inspect recent attempts or replay a failed one, open the Xebit VoiceCloud dashboard → Integrations → Webhooks → your endpoint → Deliveriesthe Xebit VoiceKit admin console → Integrations → Webhooks → your endpoint → Deliveries.