Skip to content
DutiesBook API
Open app

Appointment events

Enterprise

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.

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"
}
EventFields
appointment.cancelledappointmentId, cancelledBy (customer or staff), cancelledAt; staff’s also reason (or null) and rescheduleRequested
appointment.acceptedappointmentId, acceptedBy (staff), acceptedAt
booking_request.expiredbookingRequestId, requestId, expiredAt
booking_request.failedbookingRequestId, requestId, reason (code, message)
message.sentappointmentId, message, via (message or template)
message.failedappointmentId, message, reason
connection.revokedrevokedBy (staff), revokedAt
pingnone: 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.

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.

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:

HeaderDescription
AuthorizationBearer <the token you connected with>
X-Dutiesbook-EventThe event name
X-Dutiesbook-Event-IdSame as body.id
X-Dutiesbook-AttemptAttempt number, starting at 1
X-Dutiesbook-TimestampUnix seconds when it was signed
X-Dutiesbook-Signaturev1=<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”.