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

```sh
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.

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

```json
{
  "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:

```js
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:

```python
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:

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

The [API reference](/reference) lists every webhook route under the Aggregator tag, and the `merchant.*` webhooks show each body.
