Dumpster Controls · agent page

This is the agent-optimized version of https://dumpstercontrols.io/help/booking-api/lesson-10-webhooks-and-signature-verification: the same content as the human page, without scripts, styles, animations or navigation. People should open the full page.

Canonical page
https://dumpstercontrols.io/help/booking-api/lesson-10-webhooks-and-signature-verification
Last updated
2026-10-05
Tokens
1,126 tokens (cl100k_base), within the 2,500-token budget for a help page
Size
9.0 KB for this page, against 30 KB for the human page (70% smaller)
Markdown
https://dumpstercontrols.io/help/booking-api/lesson-10-webhooks-and-signature-verification.md, or send Accept: text/markdown to the canonical URL
Cite as
Lesson 10: webhooks and signature verification. Dumpster Controls. https://dumpstercontrols.io/help/booking-api/lesson-10-webhooks-and-signature-verification (accessed 2026-11-20).
More for agents
Facts sheet · llms.txt · llms-full.txt · All agent pages · Product manual

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
  1. ## 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.
  2. ## 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.
  3. ## 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.
  4. ## 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.
  5. ## 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.
  6. ## 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.