Appointment events
Appointments is available on Enterprise plans only, added on request. Until it's on for your
organization, every Appointments endpoint answers 403 APT_001.
DutiesBook tells your system what happens on its side: what the customer and your team did, and what reached the customer. Every event goes to your webhook URL, set in Settings › Booking, the same URL as the booking. Answer any 2xx.
The events
Section titled “The events”Every event is one JSON body: id, event, occurredAt, then its own fields.
appointment.cancelled
The customer cancelled from WhatsApp (tapped Cancel, then confirmed it), or staff cancelled in DutiesBook. Cancellations you make through the API aren’t sent back to you.
appointment.accepted
Staff accepted a pending booking in DutiesBook. Accepting it through the API afterwards answers APT_006.
booking_request.expired
The customer didn’t book before the request’s expiresAt.
booking_request.failed
WhatsApp couldn’t deliver the booking form. reason carries WhatsApp’s code and message.
message.sent / message.failed
Whether WhatsApp took a message about an appointment (accepted by WhatsApp, not yet read).
ping
Staff clicked “Check connection” in DutiesBook. Answer any 2xx. Sent once, never retried.
connection.revoked
Staff disconnected your system in DutiesBook. Connect again to resume.
{ "id": "4d7b2f0e-…", "event": "appointment.cancelled", "occurredAt": "2026-11-11T15:12:00.000Z", "appointmentId": "APT-10293", "cancelledBy": "customer", "cancelledAt": "2026-11-11T15:12:00.000Z"}{ "id": "7c41…", "event": "appointment.cancelled", "occurredAt": "2026-11-11T16:20:00.000Z", "appointmentId": "APT-10293", "cancelledBy": "staff", "cancelledAt": "2026-11-11T16:20:00.000Z", "reason": "The doctor is away that day", "rescheduleRequested": true}{ "id": "a1c9…", "event": "booking_request.failed", "occurredAt": "2026-11-11T10:00:05.000Z", "bookingRequestId": "br_6730f1c2a9e4b1d2c3e4f5a6", "requestId": "REQ-7781", "reason": { "code": "131026", "message": "Message undeliverable" }}{ "id": "e0f3…", "event": "message.sent", "occurredAt": "2026-11-11T10:04:02.000Z", "appointmentId": "APT-10293", "message": "confirmation", "via": "message"}| Event | Fields |
|---|---|
appointment.cancelled | appointmentId, cancelledBy (customer or staff), cancelledAt; staff’s also reason (or null) and rescheduleRequested |
appointment.accepted | appointmentId, acceptedBy (staff), acceptedAt |
booking_request.expired | bookingRequestId, requestId, expiredAt |
booking_request.failed | bookingRequestId, requestId, reason (code, message) |
message.sent | appointmentId, message, via (message or template) |
message.failed | appointmentId, message, reason |
connection.revoked | revokedBy (staff), revokedAt |
ping | none: just id, event, occurredAt |
rescheduleRequested: true means staff cancelled it to ask the customer for a new time: the customer’s choice arrives as a booking whose previousAppointmentId names it.
message is one of confirmation, accepted, rejected, cancelled, moved, reschedule_request, provider_changed or reminder. Only requests you sent get booking_request.* events: the forms DutiesBook sends to move an appointment don’t.
Delivery
Section titled “Delivery”An event that doesn’t get a 2xx (or any answer within 10 seconds) is tried again after 30 s, 2 min, 10 min, 30 min, 2 h and 6 h, then dropped. Every try sends the same body under the same id: deduplicate on it.
Each try goes to the webhook URL as it is then: change it in Settings › Booking and the retries follow. With no webhook URL set, events have nowhere to go and aren’t kept.
Verifying the signature
Section titled “Verifying the signature”Events and the booking are signed with the signingSecret you got when you connected, and carry your token like every call DutiesBook makes to you. Each request carries:
| Header | Description |
|---|---|
Authorization | Bearer <the token you connected with> |
X-Dutiesbook-Event | The event name |
X-Dutiesbook-Event-Id | Same as body.id |
X-Dutiesbook-Attempt | Attempt number, starting at 1 |
X-Dutiesbook-Timestamp | Unix seconds when it was signed |
X-Dutiesbook-Signature | v1=<hex> |
Recompute it over the raw body, exactly as received, and compare:
signature = "v1=" + HEX(HMAC-SHA256(signingSecret, "v1:" + body.id + ":" + timestamp + ":" + rawBody))import { createHmac, timingSafeEqual } from 'node:crypto';
function verify(signingSecret, headers, rawBody) { const id = JSON.parse(rawBody).id; const timestamp = headers['x-dutiesbook-timestamp']; const expected = 'v1=' + createHmac('sha256', signingSecret) .update(`v1:${id}:${timestamp}:${rawBody}`) .digest('hex'); return headers['x-dutiesbook-signature'] .split(',') .some((sig) => sig.trim().length === expected.length && timingSafeEqual(Buffer.from(sig.trim()), Buffer.from(expected)));}Refuse what doesn't verify
Answer 401 to a request whose signature doesn’t match, and reject old timestamps (e.g. more than 5 minutes) to stop replays. A refused booking shows the customer “This can’t be booked right now”.