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

Subscription update

Update an existing subscription

put
/tracking-push/subscribers/{id}

This endpoint updates an existing subscription's details such as the callback URL, activation status, event types, and more.

It is essential for modifying subscription settings for 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.

Authorizations
AuthorizationstringRequired

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

Path parameters
idstringRequired

The unique identifier of the subscription you want to update. This is a mandatory path parameter used to specify the subscription to be modified.

Example: a866fe22-8134-45c7-bfe9-3cf348415e26
Body
urlstring · uriRequired

The new callback URL for webhook notifications. This URL must be reachable and capable of handling POST requests.

Example: https://api.example.com/updated-webhook
isActivebooleanRequired

Specifies whether the subscription is currently active. Set to true to activate the subscription, or false to deactivate it.

Example: false
eventTypesstring[]Optional

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

If the parameter is not passed, the filter is reset and all supported events are sent.

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

Example: null
sendWarningsbooleanOptional

Indicates if the system should send email warnings about issues with the delivery of webhook notifications. Set to true to enable warnings.

Example: false
warningEmailstring · emailOptional

The email address for sending warnings. This field is necessary if sendWarnings is set to true.

Example: admin@example.com
companyTinsstring · uuid[]Optional

A list of company tax identification numbers relevant to subscriptions of type legal or recipientLegal.

  • 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.
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:
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
200

Subscription successfully updated.

application/json
idstringOptional

The unique identifier for the updated subscription.

Example: a866fe22-8134-45c7-bfe9-3cf348415e26
typestringOptional

The subscription type, such as individual, numbers, or legal.

Example: individual
urlstring · uriOptional

The updated callback URL for the subscription.

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

Indicates if the subscription is currently active.

Example: false
phonestringOptional

The phone number associated with the subscription, if applicable.

Example: 380001234567
cidstringOptional

Unique user identifier.

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

A list of event types the subscription listens to.

sendWarningsbooleanOptional

Indicates whether email warnings are sent for incorrect endpoint operations.

Example: false
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.

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.

🔸This field is optional and, if provided, must contain only Latin letters, digits, and hyphens, must not start or end with a hyphen, and must not contain spaces or other special characters.

Example: X-Custom-TokenPattern: A-Za-z0-9
updatedAtstring · date-timeOptional

The timestamp when the subscription was last updated.

Example: 2025-04-14T07:53:38.970000Z
createdAtstring · date-timeOptional

The timestamp when the subscription was created.

Example: 2025-04-14T07:53:38.970000Z
put/tracking-push/subscribers/{id}
PUT /v.1.0/tracking-push/subscribers/{id} HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 307

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

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.

PreviousNew subscription
NextSubscription deletion

Last updated