Webhooks

Webhooks push events to your endpoint as they happen, so you don't have to poll. Every delivery is signed (HMAC-SHA256), retried on failure, logged, and individually replayable.

Event catalog

Subscribe an endpoint to any of these event types. The data payload for each mirrors the corresponding API resource.

Payload

Every delivery is a POST with this envelope:

{
  "id": "evt_clz9q2k7b0001x8p3a1b2c3d4",
  "type": "shipment.created",
  "created_at": "2026-06-29T17:42:10.123Z",
  "client_id": "cl_7f2a...",
  "resource": { "type": "shipment", "id": "shp_3c1b..." },
  "data": {
    "shipmentId": "shp_3c1b...",
    "orderId": "ord_9a8b...",
    "trackingNumber": "1Z999AA10123456784",
    "carrierService": "UPS Ground",
    "shippingCost": 8.42,
    "shipCode": "SHP-10231"
  }
}

The body is additive: ignore unknown top-level keys, as you already ignore unknown event types. (client_id and resource were added on 2026-10-13; a replay of an older event carries them too.)

Headers on every delivery:

The id in the body (and x-canopy-event-id) is stable across retries and across multiple endpoints — use it to make your handler idempotent.

Verifying the signature

The signature is HMAC-SHA256 over the string `{timestamp}.{rawBody}`, base64-encoded, using your endpoint's signing secret (shown once when the endpoint is created). Verify it against the raw request body, before JSON-parsing:

import crypto from "node:crypto";

function verifyWebhook(rawBody, headers, secret, toleranceSeconds = 300) {
  const ts = headers["x-canopy-timestamp"];
  const sig = headers["x-canopy-signature"]; // "sha256=<base64>"

  // 1. Reject stale timestamps (replay protection)
  if (Math.abs(Math.floor(Date.now() / 1000) - Number(ts)) > toleranceSeconds) {
    return false;
  }

  // 2. Recompute over `${ts}.${rawBody}`
  const expected =
    "sha256=" +
    crypto.createHmac("sha256", secret).update(`${ts}.${rawBody}`).digest("base64");

  // 3. Constant-time compare
  return crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
}

Delivery & retries

Respond 2xx quickly (acknowledge, then process asynchronously). Any non-2xx — or a timeout — schedules a retry on the backoff above. An endpoint receives only events recorded after it subscribed: subscribers are resolved when the event is recorded, not at each attempt, so a new endpoint never inherits earlier events (reconcile with updatedSince for those).

Delivery logs

Every attempt is recorded. A tenant administrator reads the log for an endpoint in Settings → Webhooks → View deliveries (see Settings → Webhooks). Each row reports status (PENDING / RUNNING / SUCCEEDED / FAILED_PERMANENT), attempts, lastResponseStatus, lastError, lastAttemptAt, nextRunAt, and the originating event { id, type }.

Replay

A tenant administrator can re-send any delivery — including a permanently-failed one — from the delivery log once your endpoint is healthy. Replay re-arms the same delivery, so the body and x-canopy-event-id are identical to the original (only the timestamp and signature are recomputed). Deliveries older than the 30-day retention window are gone and cannot be replayed.

Managing endpoints

Webhook endpoints are configured by a CanopyWMS tenant administrator in Settings → Webhooks — a session-only surface, not reachable with an API token:

• Create / update / delete endpoints, each with a URL and a list of subscribed event types. A signing secret is returned once at creation.
• Rotate the signing secret at any time.
• Per-client scoping — an endpoint can receive events for the whole tenant or be pinned to a single client (brand), which also narrows what its bodies carry (see Payload).
• A tenant may have at most 25 active endpoints; creating another is refused until one is deleted or disabled.

For security, endpoint URLs must be HTTPS and resolve to a public address — requests to private, loopback, link-local, or cloud-metadata ranges are rejected, and the target is re-validated at delivery time to defend against DNS rebinding.