Webhooks
devalender sends a signed HTTPS POST to your server when a booking changes. Manage endpoints in Settings or with the CLI.
Events
booking.created: an invitee booked a slot.booking.rescheduled: a booking moved;data.previousholds the old booking.booking.cancelled: a booking was cancelled.session.created: a group session was scheduled;data.sessionholds it. Seats in a group session arrive as ordinary booking events with abooking.sessionId.session.updated: a group session's time or capacity changed;data.sessionholds it after the change anddata.previousholds the old values of only the fields that changed (startAt,endAt,capacity). Seats that move arrive asbooking.rescheduled.session.cancelled: a group session was cancelled. Each attendee also gets abooking.cancelled.ping: what "Send test" delivers. Ignore it in production handlers.
When a team booking is rescheduled onto a different member, the old member's endpoints receive booking.cancelled (the old booking) and the new member's endpoints receive booking.created (the new booking); there is no booking.rescheduled. When the same member keeps it, you get booking.rescheduled as usual.
Every payload has a unique id. Deliveries are at-least-once, so dedupe on it.
{
"id": "5b0f3c1e-8a52-4a39-9d4c-2f4f1d9a7c10",
"type": "booking.created",
"createdAt": "2030-01-07T09:00:00.000Z",
"data": {
"booking": {
"id": "11111111-1111-4111-8111-111111111111",
"eventTypeId": "22222222-2222-4222-8222-222222222222",
"hostId": "33333333-3333-4333-8333-333333333333",
"inviteeName": "Bob",
"inviteeEmail": "[email protected]",
"inviteeTimezone": "Europe/Berlin",
"startAt": "2030-01-08T10:00:00.000Z",
"endAt": "2030-01-08T10:30:00.000Z",
"status": "confirmed",
"cancelReason": null,
"rescheduledFromId": null,
"createdAt": "2030-01-07T09:00:00.000Z"
}
}
}{
"id": "…",
"type": "booking.rescheduled",
"createdAt": "2030-01-07T12:00:00.000Z",
"data": {
"booking": { "id": "…", "startAt": "2030-01-09T10:00:00.000Z", "status": "confirmed", "…": "…" },
"previous": { "id": "…", "startAt": "2030-01-08T10:00:00.000Z", "status": "rescheduled", "…": "…" }
}
}{
"id": "…",
"type": "booking.cancelled",
"createdAt": "2030-01-07T12:00:00.000Z",
"data": {
"booking": { "id": "…", "status": "cancelled", "cancelReason": "Can't make it", "…": "…" }
}
}{ "id": "…", "type": "ping", "createdAt": "2030-01-07T12:00:00.000Z", "data": {} }Headers
| Header | Value |
|---|---|
devalender-event | the event type, e.g. booking.created |
devalender-delivery | unique id of this delivery |
devalender-signature | t=<unix seconds>,v1=<hex HMAC-SHA256> |
content-type | application/json |
user-agent | devalender-webhooks/1 |
Verify the signature
The signature is HMAC-SHA256 of `${t}.${rawBody}` keyed with your endpoint's whsec_ secret. Hash the raw request body, not re-serialized JSON.
Compare with crypto.timingSafeEqual and reject any t more than 5 minutes from your clock, which stops replays.
The secret is shown once when you create the endpoint or rotate it. Rotating invalidates the old secret immediately.
const crypto = require('node:crypto');
function verifyWebhook(rawBody, signatureHeader, secret, toleranceSeconds = 300) {
const parts = Object.fromEntries(
signatureHeader.split(',').map((part) => part.split('=')),
);
const t = Number(parts.t);
if (!Number.isFinite(t)) return false;
if (Math.abs(Date.now() / 1000 - t) > toleranceSeconds) return false;
const expected = crypto
.createHmac('sha256', secret)
.update(`${t}.${rawBody}`)
.digest();
const given = Buffer.from(parts.v1 ?? '', 'hex');
return given.length === expected.length && crypto.timingSafeEqual(given, expected);
}app.post('/hooks/devalender', express.raw({ type: 'application/json' }), (req, res) => {
const ok = verifyWebhook(
req.body.toString('utf8'),
req.get('devalender-signature') ?? '',
process.env.DEVALENDER_WEBHOOK_SECRET,
);
if (!ok) return res.sendStatus(400);
const event = JSON.parse(req.body.toString('utf8'));
// Dedupe on event.id: a delivery can arrive more than once.
res.sendStatus(200);
});Retries and disabling
Reply with any 2xx within 10 seconds. Anything else (a non-2xx status, a timeout, a redirect) counts as a failure and is retried with backoff after 1 minute, 5 minutes, 30 minutes, 2, 6, 12 and 24 hours: 8 attempts in total.
After 20 consecutive failed attempts the endpoint is disabled and marked with a reason in Settings. Fix your server, then re-enable it from Settings or with devalender webhooks enable.
Limits and URL rules
- Up to 3 endpoints per account.
- URLs must use
https, with no credentials in them. - Private, loopback, link-local and cloud-metadata addresses are rejected, both when you save the URL and on every delivery.
- Redirects are not followed.
Manage endpoints with the CLI; see the CLI install steps:
devalender webhooks add https://example.com/hooks/devalender \
--events booking.created,booking.cancelled
devalender webhooks test <id>
devalender webhooks deliveries <id> --jsonPaging through deliveries
GET /api/webhooks/<id>/deliveries returns newest first, up to limit entries (1 to 200, default 50). To fetch the next page, pass the last delivery you received as the before cursor, written <createdAt>,<id>. Entries are compared at millisecond precision, so entries created in the same millisecond are ordered by id.
curl "https://devalender.com/api/webhooks/<id>/deliveries?limit=50&before=2026-11-08T14:03:22.418Z,<delivery id>" \
-H "Authorization: Bearer dvl_..."A malformed before returns 400 with the error invalid_request.
Session events and fan-out
session.created fires once per scheduled session, so a weekly series sends one per occurrence. When you cancel or change a whole session, devalender fans the change out per seat: you get one session.cancelled plus a booking.cancelled for every attendee, each with its own delivery.
Idempotency
Retries and fan-out both mean you can see the same event more than once. Treat the payload id as the idempotency key, and use the devalender-delivery header to match a request to its entry in the delivery log. Store processed ids and return 2xx for ones you have already handled.
Send test
Send test in Settings, or devalender webhooks test <id>, delivers a signed ping event to the endpoint. Use it to check your URL and signature verification before real traffic arrives.