Aug 2026: a breach at Trezor's shipping partner exposed the home addresses of nearly 12,000 customers. Read why →

Webhooks

Get notified when an order is encrypted, shipped, delivered or deleted.

1 min read

Events

Cirdan sends a webhook to your endpoint when an order changes status.

Event When it fires
order.encrypted The order is received with an encrypted address
order.label_printed The label is printed at the packing station
order.shipped The carrier scans the parcel
order.delivered The carrier confirms delivery
order.address_deleted The address is deleted and the record is written

Payload

Every payload carries the order token and never the address.

{
  "event": "order.delivered",
  "token": "ORD-7H2Q",
  "store": "st_4f9a",
  "occurred_at": "2026-09-24T14:02:11Z",
  "carrier": { "name": "DHL", "tracking": "JD014600003828" }
}

Verify the signature

Each request has a Cirdan-Signature header: an HMAC SHA-256 of the raw body with your webhook secret. Compare it in constant time before trusting the payload.

import { createHmac, timingSafeEqual } from 'node:crypto';

export function verify(body: string, header: string, secret: string) {
  const expected = createHmac('sha256', secret).update(body).digest('hex');
  return timingSafeEqual(Buffer.from(expected), Buffer.from(header));
}

Retries

Respond with any 2xx status within 10 seconds. Failed deliveries are retried with backoff for 24 hours, then marked failed in the dashboard.