Skip to content

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 ​

EventFires when
parcel.state.updatedA parcel transitions to a new workflow state
parcel.state.situation.createdA situation (sub-status) is added to the current state
parcel.isReturn.updatedA parcel's isReturn flag changes

ZR_WEBHOOK_EVENTS is the const array of all three.

The envelope ​

ts
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.

ts
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 ​

ts
import { isParcelStateUpdated, isParcelIsReturnUpdated } from '@terminaldz/zrexpress-sdk/webhooks';

if (isParcelStateUpdated(event)) { /* event.eventType is 'parcel.state.updated' */ }
if (isParcelIsReturnUpdated(event)) { /* … */ }

Consumer obligations ​

  • Respond 2xx fast (< 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 (or lastStateUpdateAt) — arrival order is not guaranteed.

Endpoint management ​

ts
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:

OptionCommand
Tailscale Funneltailscale funnel 3000
Cloudflarecloudflared tunnel --url http://localhost:3000
ngrokngrok 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.

Released under the MIT License. Not affiliated with ZR Express.