Receive webhooks
A webhook endpoint receives the events of your shipments as they happen: a signed POST of a JSON body to an HTTPS URL of yours. This guide shows how to register an endpoint, check each request, and test it with a test key.
Register an endpoint
Create the endpoint with your key. A test key creates an endpoint that receives your sandbox shipments; a live key, one that receives your live shipments.
Code
The answer carries the signing secret, whsec_..., once. Store it with your other secrets: the API never shows it again. If it leaks, delete the endpoint and create a new one.
The URL must use https on a public host name. Addresses that resolve to a private, loopback or link-local network are refused when an event is sent.
| Event | When |
|---|---|
shipment.created | You booked a shipment. |
shipment.status_changed | The shipment changed status after its booking, whatever the new status. |
shipment.delivered | The recipient has the parcel: delivered, or collected at a pickup point. |
shipment.delivery_failed | A delivery attempt failed. |
A status change to delivered sends both shipment.status_changed and shipment.delivered, to the endpoints subscribed to each.
Read an event
Each request carries these headers:
| Header | Value |
|---|---|
Shipping-Nc-Event-Id | The event id, the same on every retry and replay. |
Shipping-Nc-Event-Type | The event type, as in the body. |
Shipping-Nc-Delivery-Id | The delivery; a replay is a new delivery of the event. |
Shipping-Nc-Delivery-Attempt | The attempt number, from 1. |
Shipping-Nc-Signature | t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<body>">. |
The body is the shipment as POST /v1/aggregator/shipments returns it, and for a status change the tracking event behind it, as GET /v1/aggregator/tracking/{tracking_number} lists it:
Code
The shipment above is shortened: it has every field of the booking answer. No event ever carries the recipient.
Check the signature
Check every request before you trust it:
- Read the raw body as bytes, before any JSON parsing.
- Split
Shipping-Nc-Signatureintotandv1. - Compute the HMAC-SHA256 of
<t>.<raw body>, keyed with the wholewhsec_...secret, as lowercase hex. - Compare it with
v1in constant time. - Refuse the request when they differ, or when
tis more than 5 minutes away from your clock.
Node.js:
Code
Python:
Code
Answer and handle retries
- Answer any
2xxwithin 5 seconds, then do the work. Redirects are not followed. - A failed attempt is retried after 1, 4, 16 and 64 minutes, then about 4 and 12 hours: 7 attempts in all.
- An event can arrive more than once, and out of order. Skip the event ids you already handled, and read
data.shipment.statusfor the current status. - After 10 failed attempts in a row spread over a day, the endpoint is disabled and its pending deliveries are given up. Enable it again with
PATCH /v1/aggregator/webhook-endpoints/{id}and{ "status": "enabled" }, then replay what it missed fromGET /v1/aggregator/webhook-endpoints/{id}/deliverieswithPOST .../deliveries/{deliveryId}/replay.
Test with a test key
A test endpoint receives the events of your sandbox shipments, which no carrier sees:
shipment.createdwhen you book a shipment with the test key;shipment.status_changedwhen you cancel it;- the events of each status you ask for with
POST /v1/aggregator/shipments/{id}/simulate, such aspicked_up,out_for_delivery, thendeliveredordelivery_failed.
To check your signature code first, send a webhook.test event, tried once, and read the outcome in the answer:
Code
The API reference lists every webhook route under the Aggregator tag, and the merchant.* webhooks show each body.