Webhooks
ZR Express delivers webhooks through Svix. The @terminaldz/zrexpress-sdk/webhooks subpath provides a signature verifier, a typed event union, and narrowing guards; the zr.webhookEndpoints namespace manages endpoints.
Event types
| Event | Fires when |
|---|---|
parcel.state.updated | A parcel transitions to a new workflow state |
parcel.state.situation.created | A situation (sub-status) is added to the current state |
parcel.isReturn.updated | A parcel's isReturn flag changes |
ZR_WEBHOOK_EVENTS is the const array of all three.
The envelope
interface ParcelWebhookEvent {
eventType: 'parcel.state.updated' | 'parcel.state.situation.created' | 'parcel.isReturn.updated';
occurredAt: string; // ISO-8601 UTC — order by this, never by arrival
data: ParcelWebhookDto; // mirrors GetParcelResponse (null/empty fields omitted)
}ParcelWebhookDto mirrors GetParcelResponse with a permissive phone shape (see drift §9.4).
Verify over the RAW body
Verify the Svix signature over the raw request bytes before parsing or trusting anything. Never re-serialize the JSON first — the signature is over the exact bytes received.
import { WebhookVerifier } from '@terminaldz/zrexpress-sdk/webhooks';
const secret = (await zr.webhookEndpoints.getSecret(endpointId)).secret!; // whsec_…
const verifier = new WebhookVerifier(secret);
// In your handler — rawBody is a string/Buffer; headers carry svix-id/-timestamp/-signature:
const event = verifier.verify(rawBody, headers); // throws ZrExpressWebhookVerificationError
if (event.eventType === 'parcel.state.updated') {
console.log(event.data.trackingNumber, event.data.state?.name);
}verify throws ZrExpressWebhookVerificationError on a bad signature, a tampered body, a stale timestamp, or an unrecognized payload shape.
Narrowing guards
import { isParcelStateUpdated, isParcelIsReturnUpdated } from '@terminaldz/zrexpress-sdk/webhooks';
if (isParcelStateUpdated(event)) { /* event.eventType is 'parcel.state.updated' */ }
if (isParcelIsReturnUpdated(event)) { /* … */ }Consumer obligations
- Respond
2xxfast (< 1s) — ack, then process asynchronously.4xx= won't retry;5xx= Svix retries with backoff. - Idempotency: de-duplicate by
svix-id(deliveries can repeat). - Ordering: order by
occurredAt(orlastStateUpdateAt) — arrival order is not guaranteed.
Endpoint management
import { ZR_WEBHOOK_EVENTS } from '@terminaldz/zrexpress-sdk/webhooks';
const endpoint = await zr.webhookEndpoints.create({
url: 'https://your.app/webhooks/zr',
description: 'production',
eventTypes: [...ZR_WEBHOOK_EVENTS], // REQUIRED — see the note below
});
const { endpoints } = await zr.webhookEndpoints.list();
const secret = await zr.webhookEndpoints.getSecret(endpoint.id!);
await zr.webhookEndpoints.update(endpoint.id!, { /* … */ });
await zr.webhookEndpoints.delete(endpoint.id!);Always send eventTypes on create
The docs say "omit eventTypes to receive all events", but the live API returns 500 when the field is omitted (drift §9.15). Always send a non-empty eventTypes — to subscribe to everything, send the full ZR_WEBHOOK_EVENTS list.
Limits: max 5 endpoints per supplier, ≤ 20 custom headers per endpoint. Endpoint ids are Svix strings (ep_…), not UUIDs. zr.webhookEndpoints.getPortal() is not callable with an API key (drift §9.9).
Local testing with a tunnel
Expose a local HTTPS endpoint, register it, and drive a state change:
| Option | Command |
|---|---|
| Tailscale Funnel | tailscale funnel 3000 |
| Cloudflare | cloudflared tunnel --url http://localhost:3000 |
| ngrok | ngrok http 3000 |
A full working listener lives in examples/webhook-listener; the Playground includes a live SSE receiver. Note (drift §9.10) that ZR does not guarantee synchronous delivery for every early-workflow transition.