Merchants

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.

TerminalCode
curl -X POST "$SHIPPING_NC_API/v1/aggregator/webhook-endpoints" \ -H "Authorization: Bearer $SHIPPING_NC_KEY" \ -H 'Content-Type: application/json' \ -d '{ "url": "https://shop.example.nc/hooks/shipping", "description": "Order status sync", "event_types": ["shipment.created", "shipment.status_changed", "shipment.delivered", "shipment.delivery_failed"] }'

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.

EventWhen
shipment.createdYou booked a shipment.
shipment.status_changedThe shipment changed status after its booking, whatever the new status.
shipment.deliveredThe recipient has the parcel: delivered, or collected at a pickup point.
shipment.delivery_failedA 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:

HeaderValue
Shipping-Nc-Event-IdThe event id, the same on every retry and replay.
Shipping-Nc-Event-TypeThe event type, as in the body.
Shipping-Nc-Delivery-IdThe delivery; a replay is a new delivery of the event.
Shipping-Nc-Delivery-AttemptThe attempt number, from 1.
Shipping-Nc-Signaturet=<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:

JSONCode
{ "id": "evt_5f0c2a9e4b3d4e8a9c712d5f8b0e3a14", "type": "shipment.status_changed", "created_at": "2026-11-16T09:12:00.000Z", "mode": "live", "data": { "shipment": { "id": "0b6f9c1e-5d2a-4c3e-9f1a-7e2d8c4b6a10", "tracking_number": "SN000000014", "status": "out_for_delivery", "carrier": { "id": "2e8d4c61-7a3f-4b9e-8c15-6f0a1d3e5b72", "name": "shipping.nc" }, "merchant_reference": "CMD-20931", "sandbox": false }, "tracking_event": { "status": "out_for_delivery", "occurred_at": "2026-11-16T09:11:42.000Z", "place": "Ducos, Nouméa", "failure_reason": null } } }

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:

  1. Read the raw body as bytes, before any JSON parsing.
  2. Split Shipping-Nc-Signature into t and v1.
  3. Compute the HMAC-SHA256 of <t>.<raw body>, keyed with the whole whsec_... secret, as lowercase hex.
  4. Compare it with v1 in constant time.
  5. Refuse the request when they differ, or when t is more than 5 minutes away from your clock.

Node.js:

JavascriptCode
import { createHmac, timingSafeEqual } from 'node:crypto'; export function isGenuine(secret, signatureHeader, rawBody, nowSeconds = Date.now() / 1000) { const parts = Object.fromEntries(signatureHeader.split(',').map((part) => part.split('=', 2))); if (parts.t === undefined || parts.v1 === undefined) return false; const expected = createHmac('sha256', secret).update(`${parts.t}.`).update(rawBody).digest('hex'); const fresh = Math.abs(nowSeconds - Number(parts.t)) <= 300; return fresh && expected.length === parts.v1.length && timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1)); }

Python:

Code
import hashlib import hmac import time def is_genuine(secret: str, signature_header: str, raw_body: bytes) -> bool: parts = dict(part.split("=", 1) for part in signature_header.split(",")) timestamp, signature = parts.get("t"), parts.get("v1") if timestamp is None or signature is None: return False expected = hmac.new(secret.encode(), f"{timestamp}.".encode() + raw_body, hashlib.sha256).hexdigest() return hmac.compare_digest(expected, signature) and abs(time.time() - int(timestamp)) <= 300

Answer and handle retries

  • Answer any 2xx within 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.status for 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 from GET /v1/aggregator/webhook-endpoints/{id}/deliveries with POST .../deliveries/{deliveryId}/replay.

Test with a test key

A test endpoint receives the events of your sandbox shipments, which no carrier sees:

  • shipment.created when you book a shipment with the test key;
  • shipment.status_changed when you cancel it;
  • the events of each status you ask for with POST /v1/aggregator/shipments/{id}/simulate, such as picked_up, out_for_delivery, then delivered or delivery_failed.

To check your signature code first, send a webhook.test event, tried once, and read the outcome in the answer:

TerminalCode
curl -X POST "$SHIPPING_NC_API/v1/aggregator/webhook-endpoints/{id}/test" \ -H "Authorization: Bearer $SHIPPING_NC_KEY"

The API reference lists every webhook route under the Aggregator tag, and the merchant.* webhooks show each body.

Last modified on