Webhooks

A webhook is a way to receive shipment status changes without polling the API from your side. You specify a callback URL once, and Nova Post sends a webhook notification to it every time the status of a shipment changes.

Setting up this connection is called a subscription. This article describes how to create a subscription, manage it, and what exactly arrives at your server.

How it works

1. You create a subscription and specify the callback URL and the type of shipments you are interested in.
2. Nova Post tracks status changes of the shipments covered by this subscription.
3. As soon as a status changes, a POST request with the shipment number and its tracking history is sent to your URL.
4. Your server responds with a 2xx code — this confirms that the notification has been received.

When a webhook notification is sent

A webhook notification is sent when the status of a shipment changes to a new one.

Notifications are not sent for events that occurred before the subscription was created. Notifications are only sent while an active subscription exists.

In the tracking history, the same status code may repeat several times in a row. In this case a webhook notification is sent only once — when this status is set for the first time. The next notification arrives when the status changes to a different one.

The comparison is made against the previous status, not against the entire history. Therefore, if the status returns to a previous value after a different one, this counts as a new change and a webhook notification is sent again.

Sequence of statuses	Number of webhook notifications	For which statuses
4 → 4 → 4 → 5	2	4, 5
4 → 5 → 5 → 9	3	4, 5, 9
4 → 5 → 4	3	4, 5, 4 again

If a shipment is covered by several of your subscriptions at once, the webhook notification is sent once — the system prevents duplication. There is no need to create several subscriptions for the same shipments.

Your server's response

Your server must respond with a code in the 2xx range — this means that the notification has been accepted. Any other response, as well as no response at all, is treated as a failed delivery.

Do not perform long processing before you respond: accept the notification, put it into your own queue and return 2xx immediately, then handle the business logic separately.

Retry attempts

If your server is unavailable, does not respond in time or returns an error code, the system performs up to 6 retry attempts with increasing intervals:

Attempt	Interval after the previous one
1st retry	5 seconds
2nd retry	10 seconds
3rd retry	20 seconds
4th retry	40 seconds
5th retry	80 seconds
6th retry	160 seconds

If sendWarnings is enabled for the subscription, a warning email is sent to the address specified in warningEmail after the third failed delivery attempt of one message.

After the sixth failed attempt, resending of this message stops. The subscription itself is not changed and remains active: when the shipment status changes next time, a new webhook notification is generated and its delivery starts from the beginning.

Protection against duplicate processing

Because of retry attempts, your server may receive the same notification several times. To prevent double processing, use the x-np-attempt header.

The header has the format {message UUID}.{attempt number}:

x-np-attempt: 8f14e45f-ceea-467e-9a3a-0e1a1b1e2b1c.1
x-np-attempt: 8f14e45f-ceea-467e-9a3a-0e1a1b1e2b1c.2

Both lines are the same notification sent twice. The UUID before the dot does not change across all delivery attempts of one event and is unique for different events, which makes it the key for duplicate checks. The number after the dot shows which attempt it is.

Before you start

What to prepare

#	What is required	Description
1	A public HTTPS endpoint	An address on your server that accepts POST requests. It must be reachable from the internet and must not perform redirects.
2	A JWT-token	Required to authorize requests to the Nova Post API.
3	Your own secret token	A string that you generate yourself. Nova Post adds it to every webhook request so that your server can verify that the request really came from Nova Post.
4	A list of shipments or a rule for selecting them	Depends on the subscription type — see the "Subscription types" section.
5	A list of event types	Optional. If no filter is required, all supported events are sent. For the allowed values, see the "Event types for the eventTypes parameter" section.

The JWT-token and your own secret token are different credentials with different purposes. The JWT-token is required for Nova Post to authorize your requests. The secret token is required for you to validate incoming webhook requests. Do not use one instead of the other and do not pass the JWT-token in the callback URL.

Environments

Environment	Base URL	Purpose
Sandbox	https://api-stage.novapost.com/v.1.0/	Integration testing. In Sandbox only the test webhook can be sent — real shipment status changes do not generate webhook notifications.
PROD	https://api.novapost.com/v.1.0/	Production environment.

Webhook request structure

Headers

Header	Description
Content-Type	The Content-Type specified in the contentType parameter of the subscription. The default value is text/plain.
X-NP-Key or a custom name	The secret token of the subscription. The header name is taken from the secretTokenHeaderName parameter; if it is not set, X-NP-Key is used.
x-np-attempt	The delivery attempt identifier in the format {message UUID}.{attempt number}. Used to protect against duplicate processing.

Request body

{
  "number": "SHPL0000000001",
  "scheduled_delivery_date": "2024-11-20T20:03:00.000000Z",
  "history_tracking": [
    {
      "code": "4",
      "code_name": "On the way",
      "country_code": "UA",
      "settlement": "Kyiv",
      "date": "2024-11-19T09:32:05.000000Z"
    },
    {
      "code": "112",
      "code_name": "Change of delivery date",
      "country_code": "",
      "settlement": "",
      "date": "2024-11-19T09:33:56.000000Z"
    }
  ]
}

Parameter	Type	Description
number	string	Shipment number.
scheduled_delivery_date	string	Scheduled delivery date and time in ISO 8601 format. May be empty.
history_tracking	string[]	Array of tracking status objects.
history_tracking[].code	string	Tracking status code. Build your business logic on this parameter — it is stable. For the allowed values, see the "Tracking status codes" section.
history_tracking[].code_name	string	Tracking status name. It may change and is provided for readability only — do not use it for comparisons in your code.
history_tracking[].country_code	string	Country code where the status was recorded. May be empty.
history_tracking[].settlement	string	Settlement name. May be empty.
history_tracking[].date	string	Timestamp of the status event.

The webhook request body contains at least one tracking status. Each subsequent webhook notification contains the newly added status and all previously delivered statuses. The current status is the one with the latest date value.

Authorization

Every request to the API must contain the Authorization header with a JWT-token:

Authorization: {jwt}

The token is valid for approximately 1 hour, after which a new one must be requested. The procedure for obtaining a token is described in the Authorization article.

List of methods

Name	Description
Retrieve all subscriptions	Retrieve a list of all subscriptions associated with the client.
Create a new subscription	This endpoint is used to create a new subscription for receiving tracking notifications via webhooks. The subscription can be of various types, such as for a single number or for a company, and is essential for clients who want to receive real-time updates about shipment statuses.
Update an existing subscription	This endpoint updates an existing subscription's details such as the callback URL, activation status, event types, and more. It is used for modifying subscription settings by clients who wish to manage how they receive tracking notifications. This endpoint performs a full replacement of the settings, not a partial update. Parameters that you do not pass are reset. For example, if you change only url, the subscription loses its eventTypes filter and starts receiving webhook notifications for all events. Always pass the full set of parameters, even if you change only one of them. The subscription type cannot be changed. If you pass the type parameter with a different value in the request, the change is not applied. To switch to another type, create a new subscription and delete the old one. Please note: events that occur while the subscription is disabled are not delivered after it is enabled again.
Delete a subscription	This endpoint deletes a subscription specified by its unique identifier. Once deleted, the subscription no longer receives webhook notifications. The deletion is irreversible and should be used with caution. If you only need to stop sending webhook notifications temporarily, do not delete the subscription — disable it with the "Update an existing subscription" method by setting isActive: false. Please note: events that occur while the subscription is disabled are not delivered after it is enabled again.
Add numbers to an existing subscription	This endpoint allows adding shipment numbers to a subscription of type numbers. Only numbers that already exist in the Nova Post system are added. A number that does not yet exist in the system is not added to the subscription — it has to be added again after the shipment has been created. A 200 code means that at least one number was added, not necessarily all of the numbers passed. Always check the contents of missedNumbers.
Delete numbers from an existing subscription	This endpoint allows deleting shipment numbers from a subscription of type numbers. This endpoint returns a 200 code in any case, including when no numbers were deleted. The result of the operation is determined by the status parameter in the response body, not by the HTTP code.
Checking the test webhook	This endpoint allows you to test the webhook functionality. At least one active subscription is required for a successful response.