Developer API · updated 2026-08-22

Receive real-time webhooks

Instead of polling, let Dumpster Controls push events to your server the moment they happen. Webhooks are signed, retried with backoff, and configured entirely from Settings, API.

1. 1

   Add an endpoint

   Settings, API, Webhooks: enter a public HTTPS URL on your server and pick the events you want. Up to 5 endpoints per company. On creation you receive the endpoint's signing secret (dcwh_...), shown once: store it like a password.

2. 2

   The six events

   order.created (a new order exists), order.status_changed (includes previous_status), payment.received (an order's payment completed, including orders born already paid from online booking), lead.created, junk_job.created and junk_job.status_changed.

3. 3

   What a delivery looks like

   We POST JSON to your URL:

   { "event": "order.created", "created_at": "...", "data": { "order_number": "1042", "status": "scheduled", "payment_status": "paid", "delivery_date": "...", "pickup_date": "...", "total_price": 495, "customer_ref": "...", "created_at": "..." } }

   Headers: X-DC-Event (the event type) and X-DC-Signature (see the verification guide). Respond with any 2xx within 10 seconds to acknowledge.

4. 4

   Retries and failure handling

   Failed deliveries retry with backoff at roughly 1, 5, 30 and 120 minutes; the fifth consecutive failure drops the event and your admins are emailed. An endpoint that fails 20 times in a row is automatically disabled (also with an email); fix it and press Re-enable in Settings, API. Deliveries are at-least-once: very rarely you may receive an event twice, so make handlers idempotent (key on order_number plus event plus timestamp).

5. 5

   Rotate the secret

   The Rotate secret button issues a new signing secret (shown once) and invalidates the old one. Rotate first (the new secret only exists after rotation and the old one stops immediately), then update your server right away: any delivery that fails in the gap is retried with backoff and succeeds once your server has the new secret.