shipping.nc API

Webhooks

Server

Register an HTTPS endpoint and the events it wants: each event is sent as a POST of a JSON body (see the webhooks section of this document), with the Shipping-Nc-Event-Id, Shipping-Nc-Event-Type, Shipping-Nc-Delivery-Id, Shipping-Nc-Delivery-Attempt and Shipping-Nc-Signature headers.

Check the signature. Shipping-Nc-Signature reads t=<unix seconds>,v1=<hex>. Compute the HMAC-SHA256 of <t>.<raw body> keyed with the endpoint secret (the whole whsec_... string), compare it with the v1 value in constant time, and refuse the request when they differ or when t is more than 5 minutes from your clock. Check the raw bytes you received, before any JSON parsing.

JavascriptCode
const [t, v1] = ['t', 'v1'].map((key) => header.split(',').find((part) => part.startsWith(`${key}=`))?.slice(key.length + 1)); const expected = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex'); const valid = v1 !== undefined && v1.length === expected.length && crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(expected)) && Math.abs(Date.now() / 1000 - Number(t)) <= 300;

Answer fast. Any 2xx within 5 seconds is a success. Redirects are not followed. Anything else 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. An endpoint whose attempts all failed for a day (10 failures at least) is disabled, and its pending deliveries are given up; enable it again, then replay what it missed from its delivery log.

Endpoints must use https on a public host name: addresses that resolve to a private, loopback or link-local network are refused.


List webhook endpoints

GET
https://api.shipping.nc
/v1/webhooks/endpoints

Newest first, cursor paginated. Never returns a secret. A carrier admin manages the endpoints of the carrier, which receive every shipment; a shipper user or API key manages those of its account, which receive its own shipments only.

List webhook endpoints › query Parameters

limit
​integer · min: 1 · max: 100

Maximum number of items in the page.

Example: 25
Default: 25
cursor
​string

The next_cursor of the previous page, passed back as is. Omit it to get the first page.

Example: WyIyMDI2LTExLTExVDA4OjQyOjEwLjAwMFoiLCIwYjZmOWMxZS01ZDJhLTRjM2UtOWYxYS03ZTJkOGM0YjZhMTAiXQ

List webhook endpoints › Headers

x-correlation-id
​string · maxLength: 128

Your request identifier. Generated when absent, and always echoed in the response header.

List webhook endpoints › Responses

One page of endpoints.

​object[] · required
next_cursor
​string | null · required

Pass it as cursor to get the next page. null on the last page.


Create a webhook endpoint

POST
https://api.shipping.nc
/v1/webhooks/endpoints

The response carries the signing secret once. Each delivery is a POST of a JSON event, signed in the Shipping-Nc-Signature header; see the Webhooks tag for how to check it. A carrier admin manages the endpoints of the carrier, which receive every shipment; a shipper user or API key manages those of its account, which receive its own shipments only.

Create a webhook endpoint › Headers

x-correlation-id
​string · maxLength: 128

Your request identifier. Generated when absent, and always echoed in the response header.

Create a webhook endpoint › Request Body

url
​string · uri · maxLength: 2048 · required

An https URL on a public host name. Addresses that resolve to a private, loopback or link-local network are refused when the event is sent.

Example: https://shop.example.nc/hooks/shipping
event_types
​string[] · minItems: 1 · maxItems: 6 · required
Enum values:
shipment.created
shipment.status_changed
shipment.delivered
shipment.delivery_failed
incident.opened
incident.resolved
description
​string · maxLength: 200

Create a webhook endpoint › Responses

The new endpoint, with its signing secret.

id
​string · required
url
​string · required
description
​string | null · required
event_types
​string[] · required
Enum values:
shipment.created
shipment.status_changed
shipment.delivered
shipment.delivery_failed
incident.opened
incident.resolved
shipper_account_id
​string | null · required

The shipper account that owns the endpoint, or null for an endpoint of the carrier itself.

status
​string · enum · required
Enum values:
enabled
disabled
disabled_reason
​string | null · enum · required

manual: someone disabled it. failing: every attempt failed for a day, so it was disabled.

Enum values:
manual
failing
secret_prefix
​string · required

The first characters of the signing secret, to recognise it.

Example: whsec_Q2vN
failure_streak
​integer · min: 0 · max: 9007199254740991 · required

Attempts that failed in a row since the last success.

failing_since
​string | null · date-time · pattern: ^(?:(?:\d\d[2468][04… · required
created_at
​string · date-time · pattern: ^(?:(?:\d\d[2468][04… · required
updated_at
​string · date-time · pattern: ^(?:(?:\d\d[2468][04… · required
secret
​string · required

The signing secret, shown once. Use it to check the Shipping-Nc-Signature header of each delivery.

Example: whsec_Q2vN0cXyRk4mWb9TzL1pQe6sAfJd3uGh8iKo5aB7cD9

Get a webhook endpoint

GET
https://api.shipping.nc
/v1/webhooks/endpoints/{id}

A carrier admin manages the endpoints of the carrier, which receive every shipment; a shipper user or API key manages those of its account, which receive its own shipments only.

Get a webhook endpoint › path Parameters

id
​string · uuid · required

The webhook endpoint id.

Get a webhook endpoint › Headers

x-correlation-id
​string · maxLength: 128

Your request identifier. Generated when absent, and always echoed in the response header.

Get a webhook endpoint › Responses

The endpoint.

id
​string · required
url
​string · required
description
​string | null · required
event_types
​string[] · required
Enum values:
shipment.created
shipment.status_changed
shipment.delivered
shipment.delivery_failed
incident.opened
incident.resolved
shipper_account_id
​string | null · required

The shipper account that owns the endpoint, or null for an endpoint of the carrier itself.

status
​string · enum · required
Enum values:
enabled
disabled
disabled_reason
​string | null · enum · required

manual: someone disabled it. failing: every attempt failed for a day, so it was disabled.

Enum values:
manual
failing
secret_prefix
​string · required

The first characters of the signing secret, to recognise it.

Example: whsec_Q2vN
failure_streak
​integer · min: 0 · max: 9007199254740991 · required

Attempts that failed in a row since the last success.

failing_since
​string | null · date-time · pattern: ^(?:(?:\d\d[2468][04… · required
created_at
​string · date-time · pattern: ^(?:(?:\d\d[2468][04… · required
updated_at
​string · date-time · pattern: ^(?:(?:\d\d[2468][04… · required

Change a webhook endpoint

PATCH
https://api.shipping.nc
/v1/webhooks/endpoints/{id}

Changes only the fields sent. Disabling an endpoint gives up its pending deliveries; enabling it again clears its failure count. The secret never changes. A carrier admin manages the endpoints of the carrier, which receive every shipment; a shipper user or API key manages those of its account, which receive its own shipments only.

Change a webhook endpoint › path Parameters

id
​string · uuid · required

The webhook endpoint id.

Change a webhook endpoint › Headers

x-correlation-id
​string · maxLength: 128

Your request identifier. Generated when absent, and always echoed in the response header.

Change a webhook endpoint › Request Body

url
​string · uri · maxLength: 2048

An https URL on a public host name. Addresses that resolve to a private, loopback or link-local network are refused when the event is sent.

Example: https://shop.example.nc/hooks/shipping
description
​string | null · maxLength: 200
event_types
​string[] · minItems: 1 · maxItems: 6
Enum values:
shipment.created
shipment.status_changed
shipment.delivered
shipment.delivery_failed
incident.opened
incident.resolved
status
​string · enum

Enabling an endpoint again clears its failure count.

Enum values:
enabled
disabled

Change a webhook endpoint › Responses

The endpoint.

id
​string · required
url
​string · required
description
​string | null · required
event_types
​string[] · required
Enum values:
shipment.created
shipment.status_changed
shipment.delivered
shipment.delivery_failed
incident.opened
incident.resolved
shipper_account_id
​string | null · required

The shipper account that owns the endpoint, or null for an endpoint of the carrier itself.

status
​string · enum · required
Enum values:
enabled
disabled
disabled_reason
​string | null · enum · required

manual: someone disabled it. failing: every attempt failed for a day, so it was disabled.

Enum values:
manual
failing
secret_prefix
​string · required

The first characters of the signing secret, to recognise it.

Example: whsec_Q2vN
failure_streak
​integer · min: 0 · max: 9007199254740991 · required

Attempts that failed in a row since the last success.

failing_since
​string | null · date-time · pattern: ^(?:(?:\d\d[2468][04… · required
created_at
​string · date-time · pattern: ^(?:(?:\d\d[2468][04… · required
updated_at
​string · date-time · pattern: ^(?:(?:\d\d[2468][04… · required

Delete a webhook endpoint

DELETE
https://api.shipping.nc
/v1/webhooks/endpoints/{id}

Deletes the endpoint and its delivery log. A carrier admin manages the endpoints of the carrier, which receive every shipment; a shipper user or API key manages those of its account, which receive its own shipments only.

Delete a webhook endpoint › path Parameters

id
​string · uuid · required

The webhook endpoint id.

Delete a webhook endpoint › Headers

x-correlation-id
​string · maxLength: 128

Your request identifier. Generated when absent, and always echoed in the response header.

Delete a webhook endpoint › Responses

The endpoint is deleted.

No data returned

List the deliveries of a webhook endpoint

GET
https://api.shipping.nc
/v1/webhooks/endpoints/{id}/deliveries

Newest first, cursor paginated: what was sent, how many attempts, the last answer. A carrier admin manages the endpoints of the carrier, which receive every shipment; a shipper user or API key manages those of its account, which receive its own shipments only.

List the deliveries of a webhook endpoint › path Parameters

id
​string · uuid · required

The webhook endpoint id.

List the deliveries of a webhook endpoint › query Parameters

limit
​integer · min: 1 · max: 100

Maximum number of items in the page.

Example: 25
Default: 25
cursor
​string

The next_cursor of the previous page, passed back as is. Omit it to get the first page.

Example: WyIyMDI2LTExLTExVDA4OjQyOjEwLjAwMFoiLCIwYjZmOWMxZS01ZDJhLTRjM2UtOWYxYS03ZTJkOGM0YjZhMTAiXQ

List the deliveries of a webhook endpoint › Headers

x-correlation-id
​string · maxLength: 128

Your request identifier. Generated when absent, and always echoed in the response header.

List the deliveries of a webhook endpoint › Responses

One page of deliveries.

​object[] · required
next_cursor
​string | null · required

Pass it as cursor to get the next page. null on the last page.


Send a test event

POST
https://api.shipping.nc
/v1/webhooks/endpoints/{id}/test

Sends a signed webhook.test event now, tried once, and answers with the outcome. The endpoint must be enabled. A carrier admin manages the endpoints of the carrier, which receive every shipment; a shipper user or API key manages those of its account, which receive its own shipments only.

Send a test event › path Parameters

id
​string · uuid · required

The webhook endpoint id.

Send a test event › Headers

x-correlation-id
​string · maxLength: 128

Your request identifier. Generated when absent, and always echoed in the response header.

Send a test event › Responses

The delivery of the test event.

id
​string · required
endpoint_id
​string · required
event_id
​string · required

The id of the event sent. A replay sends the same event id again.

event_type
​string · enum · required
Enum values:
shipment.created
shipment.status_changed
shipment.delivered
shipment.delivery_failed
incident.opened
incident.resolved
webhook.test
status
​string · enum · required

pending: an attempt is due. succeeded: the endpoint answered 2xx. failed: every attempt failed.

Enum values:
pending
succeeded
failed
attempts
​integer · min: 0 · max: 9007199254740991 · required
next_attempt_at
​string | null · date-time · pattern: ^(?:(?:\d\d[2468][04… · required
last_attempt_at
​string | null · date-time · pattern: ^(?:(?:\d\d[2468][04… · required
last_status_code
​integer | null · min: -9007199254740991 · max: 9007199254740991 · required

The HTTP status of the last answer, if any.

last_error
​string | null · required

Why the last attempt failed.

Example: The endpoint answered 503
replay_of
​string | null · required

The delivery this one replays, if any.

created_at
​string · date-time · pattern: ^(?:(?:\d\d[2468][04… · required
delivered_at
​string | null · date-time · pattern: ^(?:(?:\d\d[2468][04… · required

Replay a delivery

POST
https://api.shipping.nc
/v1/webhooks/endpoints/{id}/deliveries/{deliveryId}/replay

Sends the event of a delivery again now, under the same event id, as a new delivery with its own retries. The endpoint must be enabled. A carrier admin manages the endpoints of the carrier, which receive every shipment; a shipper user or API key manages those of its account, which receive its own shipments only.

Replay a delivery › path Parameters

id
​string · uuid · required

The webhook endpoint id.

deliveryId
​string · uuid · required

The delivery id.

Replay a delivery › Headers

x-correlation-id
​string · maxLength: 128

Your request identifier. Generated when absent, and always echoed in the response header.

Replay a delivery › Responses

The new delivery.

id
​string · required
endpoint_id
​string · required
event_id
​string · required

The id of the event sent. A replay sends the same event id again.

event_type
​string · enum · required
Enum values:
shipment.created
shipment.status_changed
shipment.delivered
shipment.delivery_failed
incident.opened
incident.resolved
webhook.test
status
​string · enum · required

pending: an attempt is due. succeeded: the endpoint answered 2xx. failed: every attempt failed.

Enum values:
pending
succeeded
failed
attempts
​integer · min: 0 · max: 9007199254740991 · required
next_attempt_at
​string | null · date-time · pattern: ^(?:(?:\d\d[2468][04… · required
last_attempt_at
​string | null · date-time · pattern: ^(?:(?:\d\d[2468][04… · required
last_status_code
​integer | null · min: -9007199254740991 · max: 9007199254740991 · required

The HTTP status of the last answer, if any.

last_error
​string | null · required

Why the last attempt failed.

Example: The endpoint answered 503
replay_of
​string | null · required

The delivery this one replays, if any.

created_at
​string · date-time · pattern: ^(?:(?:\d\d[2468][04… · required
delivered_at
​string | null · date-time · pattern: ^(?:(?:\d\d[2468][04… · required