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.
Code
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
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.
query Parameters
limitMaximum number of items in the page.
cursorThe next_cursor of the previous page, passed back as is. Omit it to get the first page.
Headers
x-correlation-idYour request identifier. Generated when absent, and always echoed in the response header.
List webhook endpoints › Responses
One page of endpoints.
next_cursorPass it as cursor to get the next page. null on the last page.
Create a webhook endpoint
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.
Headers
x-correlation-idYour request identifier. Generated when absent, and always echoed in the response header.
Create a webhook endpoint › Request Body
urlAn 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.
event_typesdescriptionCreate a webhook endpoint › Responses
The new endpoint, with its signing secret.
idurldescriptionevent_typesshipper_account_idThe shipper account that owns the endpoint, or null for an endpoint of the carrier itself.
statusdisabled_reasonmanual: someone disabled it. failing: every attempt failed for a day, so it was disabled.
secret_prefixThe first characters of the signing secret, to recognise it.
failure_streakAttempts that failed in a row since the last success.
failing_since^(?:(?:\d\d[2468][04… · requiredcreated_at^(?:(?:\d\d[2468][04… · requiredupdated_at^(?:(?:\d\d[2468][04… · requiredsecretThe signing secret, shown once. Use it to check the Shipping-Nc-Signature header of each delivery.
Get a webhook endpoint
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.
path Parameters
idThe webhook endpoint id.
Headers
x-correlation-idYour request identifier. Generated when absent, and always echoed in the response header.
Get a webhook endpoint › Responses
The endpoint.
idurldescriptionevent_typesshipper_account_idThe shipper account that owns the endpoint, or null for an endpoint of the carrier itself.
statusdisabled_reasonmanual: someone disabled it. failing: every attempt failed for a day, so it was disabled.
secret_prefixThe first characters of the signing secret, to recognise it.
failure_streakAttempts that failed in a row since the last success.
failing_since^(?:(?:\d\d[2468][04… · requiredcreated_at^(?:(?:\d\d[2468][04… · requiredupdated_at^(?:(?:\d\d[2468][04… · requiredChange a webhook endpoint
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.
path Parameters
idThe webhook endpoint id.
Headers
x-correlation-idYour request identifier. Generated when absent, and always echoed in the response header.
Change a webhook endpoint › Request Body
urlAn 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.
descriptionevent_typesstatusEnabling an endpoint again clears its failure count.
Change a webhook endpoint › Responses
The endpoint.
idurldescriptionevent_typesshipper_account_idThe shipper account that owns the endpoint, or null for an endpoint of the carrier itself.
statusdisabled_reasonmanual: someone disabled it. failing: every attempt failed for a day, so it was disabled.
secret_prefixThe first characters of the signing secret, to recognise it.
failure_streakAttempts that failed in a row since the last success.
failing_since^(?:(?:\d\d[2468][04… · requiredcreated_at^(?:(?:\d\d[2468][04… · requiredupdated_at^(?:(?:\d\d[2468][04… · requiredDelete a webhook endpoint
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.
path Parameters
idThe webhook endpoint id.
Headers
x-correlation-idYour request identifier. Generated when absent, and always echoed in the response header.
Delete a webhook endpoint › Responses
The endpoint is deleted.
List the deliveries of a webhook endpoint
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.
path Parameters
idThe webhook endpoint id.
query Parameters
limitMaximum number of items in the page.
cursorThe next_cursor of the previous page, passed back as is. Omit it to get the first page.
Headers
x-correlation-idYour request identifier. Generated when absent, and always echoed in the response header.
List the deliveries of a webhook endpoint › Responses
One page of deliveries.
next_cursorPass it as cursor to get the next page. null on the last page.
Send a test event
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.
path Parameters
idThe webhook endpoint id.
Headers
x-correlation-idYour request identifier. Generated when absent, and always echoed in the response header.
Send a test event › Responses
The delivery of the test event.
idendpoint_idevent_idThe id of the event sent. A replay sends the same event id again.
event_typestatuspending: an attempt is due. succeeded: the endpoint answered 2xx. failed: every attempt failed.
attemptsnext_attempt_at^(?:(?:\d\d[2468][04… · requiredlast_attempt_at^(?:(?:\d\d[2468][04… · requiredlast_status_codeThe HTTP status of the last answer, if any.
last_errorWhy the last attempt failed.
replay_ofThe delivery this one replays, if any.
created_at^(?:(?:\d\d[2468][04… · requireddelivered_at^(?:(?:\d\d[2468][04… · requiredReplay a delivery
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.
path Parameters
idThe webhook endpoint id.
deliveryIdThe delivery id.
Headers
x-correlation-idYour request identifier. Generated when absent, and always echoed in the response header.
Replay a delivery › Responses
The new delivery.
idendpoint_idevent_idThe id of the event sent. A replay sends the same event id again.
event_typestatuspending: an attempt is due. succeeded: the endpoint answered 2xx. failed: every attempt failed.
attemptsnext_attempt_at^(?:(?:\d\d[2468][04… · requiredlast_attempt_at^(?:(?:\d\d[2468][04… · requiredlast_status_codeThe HTTP status of the last answer, if any.
last_errorWhy the last attempt failed.
replay_ofThe delivery this one replays, if any.
created_at^(?:(?:\d\d[2468][04… · requireddelivered_at^(?:(?:\d\d[2468][04… · required