Skip to main content

​
What webhooks are

Webhooks are outbound HTTPS POSTs CurbWaste sends to your registered URL after successful partner API writes. You do not poll for changes. Delivery auth is HMAC (X-CurbWaste-Signature), not your cw_live_… Bearer API key. Register endpoints and choose event types in the Developer Platform under Webhooks. API keys cannot create or manage webhooks. HTTPS is required. The signing secret (whsec_…) is shown once at create time.

​
Events

Payload contracts (envelope, headers, examples) live under Webhook payloads and the per-event pages in API Reference → Webhooks.

​
Envelope

Every delivery is JSON with: Headers mirror the envelope: X-CurbWaste-Event-Id, X-CurbWaste-Event-Type, plus X-CurbWaste-Signature.

​
Trust model

Signed payload (utf-8): {timestamp}.{rawBody} — HMAC-SHA256, hex digest. Header format: t=<unix>,s=<hex>.
Verify against the raw request body bytes. Re-serializing JSON before verification will fail the signature check.
Implementation examples live in the Webhook setup guide.

​
Reliability

Respond with 2xx quickly. Deliveries are queued and retried automatically on failure (up to 8 attempts with exponential backoff starting at 60 seconds). Prefer idempotent handlers keyed by envelope id. Deliveries you receive do not consume your company’s partner API request quota.

Webhook setup

Register an endpoint, verify signatures, and handle deliveries.

Usage

Partner request limits — webhook deliveries you receive do not count.

Customers

Account hub that emits customer lifecycle events (locations emit too).

Webhook payloads

Envelope and per-event schemas in API Reference → Webhooks.