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

• Verify webhook signatures (HMAC)
• Lesson 11: errors, limits, idempotency and the security model

© 2026 Dumpster Controls. All rights reserved. Made in the USA.

Frequently asked questions

Is Dumpster Controls really free?

Yes. The software is free: dispatch, online booking, the driver app, invoicing, the Tresha AI assistant and every other feature, with no monthly fee, no trial period and no credit card to sign up. The only cost on the free plan is optional card processing when a customer pays by card through the platform: 2.99% plus $3.99 per transaction on the free plan. An optional Unlimited plan at $169 per month lowers that to 2.99% plus $0.30. Prices as published on dumpstercontrols.io/pricing on 2026-09-23.

Do you charge per driver, per truck or per order?

No. There is no per-driver, per-truck, per-user or per-order fee, and no order limit. A company with one truck and a company with twenty pay the same for the software: nothing.

Is there a contract?

No. There is no contract, no minimum term and no setup fee. You create the account yourself, and on the free plan there is nothing to cancel because nothing is billed. The optional Unlimited plan is billed month to month.

Which countries and languages are supported?

Dumpster Controls serves hauling companies in the United States and Canada. The app interface and the Tresha AI assistant are available in English, Spanish and Portuguese. The public pages, such as the blog, the help center and the landfill finder, are in English.

How do I switch from another dumpster software?

Create a free account at dumpstercontrols.io/login, with no sales call and no credit card. Then import your customers from a CSV file using the template provided in the app; past orders can also be imported from a CSV. Container sizes and pricing are set up in Settings. The landfill database, with 1,750 active US and Canadian landfills as counted on 2026-10-01, is already loaded, so disposal sites do not need to be typed in. Step-by-step guides are at dumpstercontrols.io/help.