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.