Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

New subscription

Create a new subscription

post
/tracking-push/subscribers

This endpoint is used to create a new subscription for receiving tracking notifications via webhooks. The subscription can be of various types, such as individual or company-based, and is essential for clients who want to receive real-time updates about shipment statuses.

Authorizations
AuthorizationstringRequired

Authorization JWT-token with a lifetime of 1 hour in header

Body
typestring · enumRequired

The type of subscription to be created. This is a mandatory field and can take the following values:

  • individual — for personal accounts;
  • numbers — for tracking specific shipment numbers;
  • legal — for business accounts, requiring additional company details;
  • recipientLegal — tracks all shipments addressed to the specified legal recipient;
  • creator — tracks all shipments created by the client, regardless of whether they are specified as the sender.

See the Subscription types section.

🔹Shipment numbers are not passed when a subscription is created. For a subscription of type numbers, first create the subscription and then add the numbers with a separate request — see the Add numbers to an existing subscription method.

Possible values:
urlstring · uri · min: 3Required

The callback URL where webhook notifications will be sent. The URL must be capable of receiving POST requests with JSON payloads.

isActivebooleanRequired

Indicates whether the subscription should be active immediately upon creation. If false, the subscription is created but webhook notifications are not sent.

phonestringOptional

The phone number associated with the subscription. This parameter is required when the subscription type is individual. The phone number must be in international format.

🔸Required when type is individual.

eventTypesstring[]Optional

A list of event types that the subscription will listen to. This parameter allows you to specify which events should trigger webhook notifications.

If no value is provided, the subscription is created for all event types by default.

For the allowed values, see the Event types for the eventTypes parameter section.

sendWarningsbooleanOptional

Determines if email warnings should be sent in case of issues with the specified webhook URL. If enabled, the system sends notifications about delivery problems or other errors.

Default: false
warningEmailstring · emailOptional

The email address where warnings about endpoint issues will be sent. The email address must be valid and active to ensure delivery of warnings.

🔸Required when sendWarnings is set to true.

sendFullHistoryForMultiParcelbooleanOptional

Defines how webhook notifications are sent for multi-parcel shipments.

🔹If true, a separate webhook notification is sent for each parcel in the shipment. The request body structure remains unchanged.

Default: falseExample: false
contentTypestring · enumOptional

The Content-Type used for webhook requests. Supported values:

  • application/json — the recommended value for new integrations.
  • text/plain — a deprecated value whose support will be discontinued.

The selected value affects only the value of the Content-Type header. The structure of the request body is the same for both values.

🔹If contentType is not provided, application/json is used by default.

🔸text/plain is deprecated and its support will be discontinued. Use application/json for new integrations. If your subscription currently uses text/plain, we recommend switching to application/json in advance: the request body does not change, only the value of the Content-Type header does.

Default: application/jsonExample: application/jsonPossible values:
companyTinsstring · uuid[]Optional

A list of company tax identification numbers relevant to subscriptions of type legal or recipientLegal. This parameter is required for legal subscriptions and is essential to verify the company's identity. Each TIN must be a valid UUID.

  • For legal, the subscription receives events only for shipments where the value of the sender.companyTin field matches one of the values provided in companyTins.
  • For recipientLegal, the subscription receives events only for shipments where the value of the recipient.companyTin field matches one of the values provided in companyTins.

🔸Required when type is legal or recipientLegal.

secretTokenstring · max: 600Optional

Webhook authorization token used to validate incoming webhook requests.

🔸The token is optional and, if provided, must consist only of Latin letters and digits, up to 600 characters.

Example: k4MzM1NywiZXhwIjoxNzM3Pattern: ^[A-Za-z0-9]+$
secretTokenHeaderNamestring · nullableOptional

Header name used to transmit the secretToken in webhook requests.

If secretTokenHeaderName is provided and is not null, its value is used as the header name for transmitting the secretToken.
If secretTokenHeaderName is not provided or is explicitly set to null, the default header name X-NP-Key is used.

Validation requirements:

  • Only Latin letters, digits, and hyphens are allowed.
  • Must not start or end with a hyphen.
  • Must not contain spaces or any other special characters.

🔸This field is optional.

Example: X-Custom-TokenPattern: ^[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?$
Responses
201

Subscription successfully created.

application/json
idstringOptional

The unique identifier for the created subscription.

🔸Save the id value — it is required for all further operations with this subscription.

Example: f5300824-58a9-496b-ac3b-bee156844fdf
typestringOptional

The type of subscription created.

Example: numbers
secretTokenstring · max: 600Optional

Webhook authorization token used to validate incoming webhook requests.

🔸The token is optional and, if provided, must consist only of alphanumeric characters.

Example: k4MzM1NywiZXhwIjoxNzM3Pattern: ^[A-Za-z0-9]+$
secretTokenHeaderNamestringOptional

Specifies the name of the HTTP header used to transmit the secretToken in webhook requests.

🔸If provided, the header name must consist only of Latin letters, digits, and hyphens, must not start or end with a hyphen, and must not contain spaces or other special characters.

🔸This field is optional.

Example: X-Custom-TokenPattern: A-Za-z0-9
urlstring · uriOptional

The callback URL for the subscription.

Example: https://api.example.com/webhook
isActivebooleanOptional

Indicates if the subscription is currently active.

Example: true
phonestringOptional

The phone number associated with the subscription.

Example: 380630000001
cidstringOptional

Unique user identifier

Example: 11a111a1-a1a1-11aa-a111-111111aa1111
eventTypesstring[]Optional

The list of event types the subscription listens to:

  • ReadyToShip: The shipment has been created and is ready for dispatch.
  • Deleted: The shipment has been deleted.
  • ParcelPlaceRemoved: A parcel has been removed from the shipment.
  • Received: The shipment has been received by the recipient.
  • MoneyTransfer: A money transfer related to the shipment has been created.
  • MoneyTransferReceived: The money transfer related to the shipment has been paid out to the recipient.
  • Returned: The shipment is being returned or has been returned to the sender.
  • Refused: The recipient has refused to accept the shipment.
  • Redirecting: The shipment is being redirected to another address or branch.
  • Utilization: The shipment has been disposed of.
  • Redelivery: A repeat delivery attempt for the shipment has been scheduled.
  • UndeliveryReason: A non‑delivery reason has been recorded.
  • ChangeTime: The delivery date or time has been changed.
  • ArrivalSC: The shipment has arrived at the sorting center.
  • TransferToPartner: The shipment has been handed over to a partner for further delivery.
  • LoadingCourier: The shipment has been loaded onto the courier’s vehicle.
  • ArrivalSenderWarehouse: The shipment has arrived at the sender’s warehouse.
  • DepartureSenderWarehouse: The shipment has departed from the sender’s warehouse.
  • InCityRecipient: The shipment has arrived in the recipient’s city.
  • AwaitingOnDivision: The shipment is waiting at the branch or pickup point.

🔸This field accepts only the event types listed above.
Any values outside of this list are not supported and must not be provided.

Example: ["ReadyToShip"]
sendWarningsbooleanOptional

Indicates whether email warnings are sent for incorrect endpoint operations.

Example: true
warningEmailstring · emailOptional

The email address used for sending warnings.

Example: admin@example.com
sendFullHistoryForMultiParcelbooleanOptional

Defines how webhook notifications are sent for multi-parcel shipments.

🔹If true, a separate webhook notification is sent for each parcel in the shipment. The request body structure remains unchanged.

Default: falseExample: false
contentTypestringOptional

Specifies the Content-Type used for webhook request payloads. The default value is application/json.

Example: application/json
companyTinsstring[]Optional

The list of company tax identification numbers of a legal entity associated with the subscription.

updatedAtstring · date-timeOptional

The timestamp when the subscription was last updated.

Example: 2024-02-26T20:08:26.217000Z
createdAtstring · date-timeOptional

The timestamp when the subscription was created.

Example: 2024-02-26T20:08:26.217000Z
post/tracking-push/subscribers
POST /v.1.0/tracking-push/subscribers HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 372

{
  "type": "numbers",
  "url": "https://api.webhook.test/test_endpoint",
  "isActive": true,
  "phone": "",
  "eventTypes": [
    "ReadyToShip",
    "Received",
    "Returned"
  ],
  "sendWarnings": true,
  "warningEmail": "example@novadigital.com",
  "sendFullHistoryForMultiParcel": false,
  "contentType": "application/json",
  "companyTins": [],
  "secretToken": "k4MzM1NywiZXhwIjoxNzM3",
  "secretTokenHeaderName": "X-Custom-Token"
}
{
  "id": "a866fe22-8134-45c7-bfe9-3cf348415e26",
  "type": "numbers",
  "url": "https://api.somehost.link/endpoint",
  "isActive": true,
  "phone": "",
  "cid": "11a111a1-a1a1-11aa-a111-111111aa1111",
  "eventTypes": [
    "ReadyToShip"
  ],
  "sendWarnings": true,
  "sendFullHistoryForMultiParcel": false,
  "contentType": "application/json",
  "companyTins": [],
  "secretToken": "k4MzM1NywiZXhwIjoxNzM3",
  "secretTokenHeaderName": "X-Custom-Token",
  "warningEmail": "someuser@novadigital.com",
  "updatedAt": "2025-04-14T07:26:20.994000Z",
  "createdAt": "2025-04-14T07:26:20.994000Z"
}

Deprecated parameters

Some parameters are duplicated in snake_case notation. These parameters are kept solely for backward compatibility — use the camelCase variants for new integrations.

Deprecated parameter
Use instead

is_active

isActive

event_types

eventTypes

send_warnings

sendWarnings

warning_email

warningEmail

company_tins

companyTins

secret_token

secretToken

secret_token_header_name

secretTokenHeaderName

created_at

createdAt

updated_at

updatedAt

The same deprecated parameters are present in the responses to subscription creation and update. They are not repeated further in this article.

PreviousSubscription list
NextSubscription update

Last updated