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

# Webhooks overview

> Signed JSON POSTs to your endpoint when things happen — no polling.

Traddal delivers signed JSON POSTs to your endpoints when things happen to
your consignments, manifests, and shipments. Manage endpoints on
**Settings → Developers → Webhooks** or via the Admin API at
`/admin/api/v1/settings/webhooks` (CRUD, plus `POST /{id}/rotate-secret`,
`POST /{id}/test`, and `GET /{id}/deliveries`).

## Delivery model

* **At-least-once.** Deliveries are written to a durable outbox and posted by
  a worker every minute. Dedupe on the delivery `id` if you must process
  exactly once.
* **Retries with backoff** — roughly 1m, 5m, 30m, 2h, 6h — then the delivery
  is marked failed. Per-endpoint history is visible on the Developers page.
* **Sandbox vs live** — sandbox-mode endpoints receive sandbox events only;
  live endpoints receive live events.

## Payload

```json theme={null}
{
  "id": "whd_01J9ZK...",
  "type": "consignment.created",
  "created_at": "2026-07-19T09:12:04Z",
  "data": {
    "consignment_id": "cons_01J9ZK...",
    "shipment_ref": "SHIP-1001",
    "external_code": "erp-4412"
  }
}
```

Consignment-derived events carry `data.shipment_ref` and
`data.external_code` alongside `data.consignment_id`, so you can correlate on
your own references without a lookup.

## Subscribing

Subscriptions are exact event types or category wildcards (`manifest.*`). An
empty subscription list subscribes to **everything**.

<Card title="Verify signatures" icon="shield-check" href="/webhooks/verify">
  Every delivery is HMAC-signed. Always verify before trusting a payload.
</Card>