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

EventWhen it fires
appointment.createdAn appointment is booked in the dashboard or by the AI voice agent.
appointment.updatedAn appointment's details are changed in the dashboard.
appointment.cancelledAn appointment is cancelled in the dashboard.
appointment.completedAn appointment is marked completed in the dashboard.
slot.createdA calendar window is created in the dashboard.
slot.updatedA calendar window is changed in the dashboard.

Event payloads

appointment.* events

All four appointment events share one shape.

JSON
{
  "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"
  }
}
FieldDescription
event_idUnique identifier of this delivery.
eventappointment.created, appointment.updated, appointment.cancelled or appointment.completed.
timestampISO 8601 UTC time the event was sent.
appointment.appointment_idAppointment identifier.
appointment.appointment_typeService UUID.
appointment.appointment_type_nameReadable service name.
appointment.branch_idBranch UUID.
appointment.dateAppointment date, YYYY-MM-DD.
appointment.start_timeFull ISO 8601 UTC date and time of the appointment.
appointment.sessionSession name.
appointment.batchBatch label.
appointment.tokenQueue token, if one was assigned.
appointment.patient_namePatient name.
appointment.parent_phonePatient phone number.
appointment.doctor_nameAssigned doctor, if set.
appointment.statusCurrent status.
appointment.booked_viaHow it was created: "phone_call" for the AI agent, "dashboard" for manual entry.
appointment.booked_atISO 8601 UTC time the appointment was created.

slot.* events

Both slot events share one shape.

JSON
{
  "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:

HeaderDescription
X-Webhook-TimestampUnix time in seconds when the payload was signed.
X-Webhook-Signaturev1=<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"

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:

AttemptDelay
1Immediate
230 seconds
32 minutes
410 minutes
51 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.