Webhooks

type WebhookEnvelope = {
  id: string;            // "evt_…", the same for every retry and every endpoint
  type: "booking.created" | "booking.failed" | "ping";
  created: string;       // ISO 8601
  apiVersion: "2026-09-01";
  data: BookingWebhookData | { message: string };  // { message } for ping
};

{
  "id": "evt_3f9a1c2b7d8e4f60a1b2c3d4e5f60718",
  "type": "booking.created",
  "created": "2026-09-24T10:15:32.418Z",
  "apiVersion": "2026-09-01",
  "data": {
    "booking": {
      "reference": "BXP-7K3M9Q",
      "id": "AAMkAGI2TG93AAA=",
      "status": "confirmed",
      "start": "2026-10-02T14:00:00.000Z",
      "end": "2026-10-02T14:45:00.000Z",
      "timeZone": "Europe/London",
      "service": { "id": "a1b2c3", "name": "Initial consultation" },
      "staff": [{ "id": "d4e5f6", "name": "Sam Lee" }],
      "customer": {
        "name": "Alex Morgan",
        "email": "alex@example.com",
        "phone": "+44 20 7946 0000",
        "notes": "Knee injury from running."
      },
      "answers": [
        { "questionId": "q1", "question": "Is this your first visit?", "answer": "Yes" }
      ],
      "manageUrl": "https://outlook.office.com/book/…",
      "joinUrl": null
    },
    "business": { "id": "ContosoPhysio@contoso.com", "name": "Contoso Physio" },
    "widget": { "id": "w_8fk2m1qz", "name": "Website – main" },
    "attribution": {
      "source": "google",
      "medium": "cpc",
      "campaign": "brand",
      "channel": "Paid search",
      "landingPage": "/pricing?utm_source=google&utm_medium=cpc&utm_campaign=brand&gclid=Cj0KCQ…",
      "referrer": "https://www.google.com/",
      "pageUrl": "https://www.example.com/book",
      "utm": { "source": "google", "medium": "cpc", "campaign": "brand", "term": "physio near me" },
      "clickIds": { "gclid": "Cj0KCQ…" },
      "gaClientId": "1234567890.1727172000"
    }
  }
}

{
  "booking": {
    "reference": "BXP-Q2W8ZT",
    "id": null,
    "status": "failed",
    "customer": null,
    "answers": [],
    "error": { "code": "upstream", "message": "…" }
  }
}

{
  "id": "evt_9c1d…",
  "type": "ping",
  "created": "2026-09-24T10:20:00.000Z",
  "apiVersion": "2026-09-01",
  "data": { "message": "Test notification from BookingsXP" }
}

v1 = hex( HMAC_SHA256( secret, "<t>.<raw body>" ) )

import crypto from "node:crypto";
import express from "express";

const SECRET = process.env.BOOKINGSXP_WEBHOOK_SECRET; // whsec_…

export function verify(rawBody, header, secret) {
  if (!header) return false;
  const { t, v1 } = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  if (!t || !v1) return false;
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false; // replay window
  const mac = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  const a = Buffer.from(mac);
  const b = Buffer.from(v1);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

const app = express();

app.post("/webhooks/bookingsxp", express.raw({ type: "application/json" }), (req, res) => {
  const raw = req.body.toString("utf8");
  if (!verify(raw, req.get("BookingsXP-Signature"), SECRET)) return res.sendStatus(400);

  const event = JSON.parse(raw);
  if (event.type === "booking.created") {
    const { reference, start, service, customer } = event.data.booking;
    // Upsert by reference so a retried delivery does not create a duplicate.
    console.log(`${reference}: ${customer.name} booked ${service.name} at ${start}`);
  }
  res.sendStatus(204);
});

app.listen(3000);

import hashlib
import hmac
import json
import os
import time

from flask import Flask, abort, request

SECRET = os.environ["BOOKINGSXP_WEBHOOK_SECRET"]  # whsec_…
app = Flask(__name__)


def verify(raw_body: bytes, header: str, secret: str) -> bool:
    try:
        parts = dict(p.split("=", 1) for p in header.split(","))
        t, v1 = parts["t"], parts["v1"]
    except (AttributeError, KeyError, ValueError):
        return False
    if abs(time.time() - int(t)) > 300:
        return False
    signed = f"{t}.".encode() + raw_body
    mac = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(mac, v1)


@app.post("/webhooks/bookingsxp")
def bookingsxp_webhook():
    raw = request.get_data()
    if not verify(raw, request.headers.get("BookingsXP-Signature", ""), SECRET):
        abort(400)
    event = json.loads(raw)
    if event["type"] == "booking.created":
        booking = event["data"]["booking"]
        print(booking["reference"], booking["customer"]["email"])
    return "", 204

New booking: Alex Morgan · Initial consultation · Fri, Oct 2, 3:00 PM BST
Service: Initial consultation        When: Fri, Oct 2, 3:00 PM BST
With: Sam Lee                        Source: google / cpc · brand
Customer: Alex Morgan <alex@example.com>
Ref: BXP-7K3M9Q
via Website – main · Contoso Physio

{
  "type": "message",
  "attachments": [
    {
      "contentType": "application/vnd.microsoft.card.adaptive",
      "content": {
        "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
        "type": "AdaptiveCard",
        "version": "1.4",
        "body": [
          { "type": "TextBlock", "text": "New booking: Alex Morgan · Initial consultation · Fri, Oct 2, 3:00 PM BST", "weight": "Bolder", "size": "Medium", "wrap": true },
          { "type": "FactSet", "facts": [
            { "title": "Service", "value": "Initial consultation" },
            { "title": "When", "value": "Fri, Oct 2, 3:00 PM BST" },
            { "title": "Source", "value": "google / cpc · brand" },
            { "title": "Reference", "value": "BXP-7K3M9Q" }
          ] }
        ]
      }
    }
  ]
}