> ## Documentation Index
> Fetch the complete documentation index at: https://docs.curbwaste.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Understand outbound CurbWaste webhooks — signed HTTPS deliveries, event catalog, and how they differ from REST API keys.

## What webhooks are

Webhooks are **outbound** HTTPS `POST`s 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](https://platform.curbwaste.com) under **Webhooks**. API keys cannot create or manage webhooks. HTTPS is required. The signing secret (`whsec_…`) is shown once at create time.

## Events

| Event | When |
| - | - |
| `customer.created` | After successful `POST /v1/customers` |
| `customer.updated` | After successful `PATCH /v1/customers/{id}` |
| `location.created` | After a location create that writes a new record |
| `location.updated` | After a location write that mutates data (PATCH, reactivate, PO fill-in, …) |

Payload contracts (envelope, headers, examples) live under [Webhook payloads](/api-reference/webhooks) and the per-event pages in **API Reference → Webhooks**.

## Envelope

Every delivery is JSON with:

| Field | Meaning |
| - | - |
| `id` | Event id (`evt_…`) — use for idempotency |
| `type` | Event name (e.g. `customer.created`) |
| `createdAt` | When the event was emitted (ISO-8601) |
| `data` | Full profile for that resource |

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>`.

<Warning>
  Verify against the **raw** request body bytes. Re-serializing JSON before verification will fail the signature check.
</Warning>

Implementation examples live in the [Webhook setup](/guides/webhooks-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](/api-reference/usage).

## Related

<CardGroup cols={2}>
  <Card title="Webhook setup" icon="webhook" href="/guides/webhooks-setup">
    Register an endpoint, verify signatures, and handle deliveries.
  </Card>

  <Card title="Usage" icon="gauge-high" href="/api-reference/usage">
    Partner request limits — webhook deliveries you receive do not count.
  </Card>

  <Card title="Customers" icon="users" href="/concepts/customers">
    Account hub that emits customer lifecycle events (locations emit too).
  </Card>

  <Card title="Webhook payloads" icon="code" href="/api-reference/webhooks">
    Envelope and per-event schemas in API Reference → Webhooks.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.