Booking API course · updated 2026-10-05
Lesson 10: webhooks and signature verification
Webhooks tell your site or CRM that an order landed, without polling. They are registered in the app, signed with HMAC-SHA256, retried with backoff, and need no approval. This lesson covers the events, the payload, the signature check and idempotency.
Before you start
- Admin access to Online Booking, Developers
- An https endpoint on a public domain
- ## Register an endpoint
In Online Booking, Developers, under "Webhooks", enter an https URL, pick the events and click Add. The signing secret (dcwh_...) is shown once; keep it in your backend. Up to 3 endpoints. Private and local hosts are refused; https is required. - ## Events
booking.completed: an online order was created and confirmed (hosted page, widget or API). booking.held: an online order was received but held for manual review. booking.released: a held order was approved and left the review. Payload data: order_number, status, payment_status, delivery_date, pickup_date, total_price, booking_channel (link, widget or api), order_id, customer_ref, created_at, plus previous_status on booking.released. - ## Delivery and signature
```
POST https://your-endpoint
Content-Type: application/json
X-DC-Signature: t=1760000000,v1=<hex HMAC-SHA256 of "<t>.<raw body>" with your dcwh_ secret>
```
{ "event": "booking.completed", "created_at": "2026-10-05T12:00:00Z", "data": { ... } }
```
Answer 2xx within 10 seconds. Anything else is retried with backoff at roughly 1, 5, 30, 120 and 360 minutes; after the fifth failure the event is dropped and the company's admins are emailed. After 20 consecutive failures the endpoint is switched off. - ## Verify in Node
```
import crypto from "node:crypto";
function verify(rawBody, header, secret) {
const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
const expected = crypto.createHmac("sha256", secret).update(${parts.t}.${rawBody}).digest("hex");
const given = String(parts.v1 || "");
if (given.length !== 64) return false;
if (Math.abs(Date.now() / 1000 - Number(parts.t)) > 300) return false;
return crypto.timingSafeEqual(Buffer.from(expected, "hex"), Buffer.from(given, "hex"));
}
```
Use the raw request body, not a re-serialized JSON. The Python version is in the data API manual: How to verify webhook signatures. - ## Idempotency
Deliveries are at-least-once. Key your handler on order_number plus event: a second delivery of the same event must be a no-op. - ## material in the payload
booking.completed, booking.held and booking.released carry material (the slug, or the free text the order has) and material_label (from the order's material snapshot). Both are null when the order has no material. New keys may appear in data over time; never reject unknown keys.
What happens next
- Webhooks are optional: POST /confirm already returns the order number synchronously. Use them for your CRM, your inbox or your own dashboard.
Troubleshooting
My endpoint was switched off.
Twenty consecutive failures (non-2xx or timeout). Fix the endpoint, delete it and add it again in the app.
Related guides
© 2026 Dumpster Controls. All rights reserved. Made in the USA.