Skip to content
Docs

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.previous holds the old booking.
  • booking.cancelled: a booking was cancelled.
  • session.created: a group session was scheduled; data.session holds it. Seats in a group session arrive as ordinary booking events with a booking.sessionId.
  • session.updated: a group session's time or capacity changed; data.session holds it after the change and data.previous holds the old values of only the fields that changed (startAt, endAt, capacity). Seats that move arrive as booking.rescheduled.
  • session.cancelled: a group session was cancelled. Each attendee also gets a booking.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

HeaderValue
devalender-eventthe event type, e.g. booking.created
devalender-deliveryunique id of this delivery
devalender-signaturet=<unix seconds>,v1=<hex HMAC-SHA256>
content-typeapplication/json
user-agentdevalender-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> --json

Paging 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.