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

Webhooks

Retrieve all subscriptions

get
/tracking-push/subscribers

Retrieve a list of all subscriptions associated with the client.

Authorizations
AuthorizationstringRequired

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

Responses
200

Successful response containing a list of subscriptions.

application/json
current_pageintegerOptional

The current page of the paginated result set.

Example: 1
last_pageintegerOptional

The last page of the paginated result set.

Example: 1
per_pageintegerOptional

The number of items per page.

Example: 15
totalintegerOptional

The total number of subscription items available.

Example: 1
get/tracking-push/subscribers
GET /v.1.0/tracking-push/subscribers HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Accept: */*

{
  "current_page": 1,
  "last_page": 1,
  "per_page": 15,
  "total": 3,
  "items": [
    {
      "id": "a47388e8-2af0-447e-a33b-1484b79b6331",
      "type": "numbers",
      "url": "https://api.somehost.link/endpoint",
      "isActive": true,
      "is_active": true,
      "phone": "",
      "cid": "11a111a1-a1a1-11aa-a111-111111aa1111",
      "eventTypes": [
        "ReadyToShip"
      ],
      "event_types": [
        "ReadyToShip"
      ],
      "sendWarnings": true,
      "send_warnings": true,
      "warningEmail": "someuser@novadigital.com",
      "warning_email": "someuser@novadigital.com",
      "contentType": "application/json",
      "companyTins": [],
      "company_tins": [],
      "secretToken": "k4MzM1NywiZXhwIjoxNzM3",
      "secret_token": "k4MzM1NywiZXhwIjoxNzM3",
      "secretTokenHeaderName": null,
      "secret_token_header_name": null,
      "updatedAt": "2025-04-14T07:26:20.994000Z",
      "updated_at": "2025-04-14T07:26:20.994000Z",
      "createdAt": "2025-04-14T07:26:20.994000Z",
      "created_at": "2025-04-14T07:26:20.994000Z",
      "numbers": []
    }
  ]
}

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.

Webhook notifications are sent using the application/json Content-Type by default.

Authorizations
AuthorizationstringRequired

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

Query parameters
typestring · enumRequired

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

  • 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: To tracking all shipments created by the client, regardless of whether they are specified as the sender.
Example: numbersPossible values:
urlstring · uri · min: 3Required

The callback URL where webhook notifications will be sent. This is a mandatory field and must be a valid URL. The URL should be capable of receiving POST requests with JSON payloads.

Example: https://api.webhook.test/test_endpoint
isActivebooleanRequired

Indicates whether the subscription should be active immediately upon creation. If set to true, the webhook will start sending notifications as soon as the subscription is confirmed. Defaults to false if not provided.

Default: falseExample: true
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, for example, 380637445555.

Example: 380630000001
secretTokenstringOptional

Webhook Authorization Token: Maximum Length 600 Characters

Example: k4MzM1NywiZXhwIjoxNzM3
secretTokenHeaderNamestringOptional

Specifies the header name used to pass the secretToken in webhook requests.

Example: X-Custom-Token
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 will be created for all event types by default.

The list of supported event types includes:

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

sendWarningsbooleanOptional

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

Default: falseExample: true
warningEmailstring · emailOptional

The email address where warnings about endpoint issues will be sent. It is required if sendWarnings is set to true. The email address should be valid and active to ensure delivery of warnings.

Example: example@novadigital.com
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 should be a valid UUID.

Body
typestring · enumRequired

The type of subscription to be created.

Possible values:
urlstring · uriRequired

The callback URL where webhook notifications will be sent.

isActivebooleanRequired

Indicates whether the subscription is active immediately after creation.

phonestringOptional

The phone number associated with the subscription.

eventTypesstring[]Optional

A list of event types that the subscription will listen to.

sendWarningsbooleanOptional

Determines if email warnings should be sent for webhook delivery issues.

warningEmailstring · emailOptional

The email address where warnings will be sent.

companyTinsstring · uuid[]Optional

A list of company tax identification numbers for legal subscriptions.

  • 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 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 secretTokenHeaderName is provided and is not null, its value is used as the header name for transmitting the secretToken.
If secretTokenHeaderName is not provided in the request, 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
Responses
201

Subscription successfully created.

application/json
idstringOptional

The unique identifier for the created 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]+$
secret_tokenstring · max: 600Optional

Deprecated. Legacy field kept for backward compatibility. Use secretToken instead.

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
secret_token_header_namestringOptional

Deprecated. Legacy field kept for backward compatibility. Use secretTokenHeaderName instead.

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
is_activebooleanOptional

Deprecated. Legacy field kept for backward compatibility. Use isActive instead.

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"]
event_typesstring[]Optional

Deprecated. Legacy field kept for backward compatibility. Use eventTypes instead.

Example: ["ReadyToShip"]
sendWarningsbooleanOptional

Indicates whether email warnings are sent for incorrect endpoint operations.

Example: true
send_warningsbooleanOptional

Deprecated. Legacy field kept for backward compatibility. Use sendWarnings instead.

Example: true
warningEmailstring · emailOptional

The email address used for sending warnings.

Example: admin@example.com
warning_emailstring · emailOptional

Deprecated. Legacy field kept for backward compatibility. Use warningEmail instead.

Example: admin@example.com
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.

company_tinsstring[]Optional

Deprecated. Legacy field kept for backward compatibility. Use companyTins instead.

updatedAtstring · date-timeOptional

The timestamp when the subscription was last updated.

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

Deprecated. Legacy field kept for backward compatibility. Use updatedAt instead.

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

The timestamp when the subscription was created.

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

Deprecated. Legacy field kept for backward compatibility. Use createdAt instead.

Example: 2024-02-26T20:08:26.217000Z
post/tracking-push/subscribers
POST /v.1.0/tracking-push/subscribers?type=numbers&url=https%3A%2F%2Fapi.webhook.test%2Ftest_endpoint&isActive=false HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 301

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

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.

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
typestring · enumOptional

The type of subscription created.

Example: recipientLegalPossible values:
eventTypesstring[]Optional

A list of event types that the subscription will listen for. You can specify which events should trigger webhook notifications.

Example: null
sendWarningsbooleanOptional

Indicates if the system should send email warnings about issues with the specified webhook URL. 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.
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 secretTokenHeaderName is provided and is not null, its value is used as the header name for transmitting the secretToken.
If secretTokenHeaderName is not provided in the request, 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
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
is_activebooleanOptional

Deprecated. Legacy field kept for backward compatibility. Use isActive instead.

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.

event_typesstring[]Optional

Deprecated. Legacy field kept for backward compatibility. Use eventTypes instead.

sendWarningsbooleanOptional

Indicates whether email warnings are sent for incorrect endpoint operations.

Example: false
send_warningsbooleanOptional

Deprecated. Legacy field kept for backward compatibility. Use sendWarnings instead.

Example: false
warningEmailstring · emailOptional

The email address used for sending warnings.

Example: admin@example.com
warning_emailstring · emailOptional

Deprecated. Legacy field kept for backward compatibility. Use warningEmail instead.

Example: admin@example.com
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.

company_tinsstring[]Optional

Deprecated. Legacy field kept for backward compatibility. Use companyTins instead.

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]+$
secret_tokenstring · max: 600Optional

Deprecated. Legacy field kept for backward compatibility. Use secretToken instead.

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.

Pattern: A-Za-z0-9
secret_token_header_namestringOptional

Deprecated. Legacy field kept for backward compatibility. Use secretTokenHeaderName instead.

Example: X-Custom-Token
updatedAtstring · date-timeOptional

The timestamp when the subscription was last updated.

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

Deprecated. Legacy field kept for backward compatibility. Use updatedAt instead.

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

The timestamp when the subscription was created.

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

Deprecated. Legacy field kept for backward compatibility. Use createdAt instead.

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: 236

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

Delete a subscription

delete
/tracking-push/subscribers/{id}

This endpoint deletes a subscription specified by its unique identifier. Once deleted, the subscription will no longer receive webhook notifications. The deletion is irreversible and should be used with caution.

Authorizations
AuthorizationstringRequired

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

Path parameters
idstringRequired

The unique identifier of the subscription to be deleted. This is a required path parameter that identifies the specific subscription you wish to remove.

Example: a866fe22-8134-45c7-bfe9-3cf348415e26
Responses
204

Subscription successfully deleted.

application/json
messagestringOptional

A confirmation message indicating successful deletion of the subscription.

delete/tracking-push/subscribers/{id}
DELETE /v.1.0/tracking-push/subscribers/{id} HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Accept: */*

{
  "message": null
}

Add numbers to an existing subscription

post
/tracking-push/subscribers/{id}/numbers

This endpoint allows adding shipment numbers to an existing subscription specified by its unique identifier. The numbers are essential for tracking specific shipments associated with the subscription.

Authorizations
AuthorizationstringRequired

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

Path parameters
idstringRequired

The unique identifier of the subscription to which shipment numbers will be added. This is a required path parameter.

Example: a866fe22-8134-45c7-bfe9-3cf348415e26
Body
numbersstring[]Optional

A list of shipment numbers to be added to the subscription.

Example: ["20600000179995","20600000179992"]
Responses
200

Numbers successfully added to the subscription.

application/json
messagestringOptional

A confirmation message indicating successful addition of numbers.

Example: Numbers successfully added to the subscription.
addedNumbersstring[]Optional

The list of numbers that were successfully added to the subscription.

Example: ["SHPL2666212296","SHPL6628713835"]
missedNumbersstring[]Optional

The list of numbers that could not be added (e.g., invalid or already linked).

post/tracking-push/subscribers/{id}/numbers
POST /v.1.0/tracking-push/subscribers/{id}/numbers HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 47

{
  "numbers": [
    "20600000179995",
    "20600000179992"
  ]
}
{
  "message": "Numbers successfully added to the subscription.",
  "addedNumbers": [
    "SHPL2666212296",
    "SHPL6628713835"
  ],
  "missedNumbers": []
}

Delete numbers from an existing subscription

delete
/tracking-push/subscribers/{id}/numbers

This endpoint allows deleted shipment numbers from an existing subscription specified by its unique identifier.

Authorizations
AuthorizationstringRequired

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

Path parameters
idstringRequired

The unique identifier of the subscription to which shipment numbers will be deleted. This is a required path parameter.

Example: a866fe22-8134-45c7-bfe9-3cf348415e26
Body
numbersstring[]Optional

A list of shipment numbers to be deleted to the subscription.

Example: ["20600000179995","20600000179992"]
Responses
200

Numbers successfully deleted with subscription.

application/json
messagestringOptional

A confirmation message indicating successful deleted of numbers.

delete/tracking-push/subscribers/{id}/numbers
DELETE /v.1.0/tracking-push/subscribers/{id}/numbers HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 47

{
  "numbers": [
    "20600000179995",
    "20600000179992"
  ]
}
{
  "message": {}
}

Checking the test webhook

post
/tracking-push/subscribers/test-webhook

This endpoint allows you to test the webhook functionality. At least one active subscription is required for a successful response.

Webhook requests are sent using the application/json Content-Type by default.

🔹Test webhook behavior: The method returns a confirmation response indicating that a test webhook request was sent. A webhook event with tracking data is delivered to the subscriber endpoint.

🔹Webhook payload parameters: The webhook request body looks as follows:

{
  "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"
    }
  ]
}

with the following parameters:

  • number — shipment number.

  • scheduled_delivery_date — scheduled delivery date and time in ISO 8601 format.

  • history_tracking — array of tracking status objects.

    • code — tracking status code. For more details about tracking status codes, see the description of the currentStatus.statusCode parameter in the response of the FullTracking method.

    • code_name — tracking status name.

    • country_code — country code where the status was recorded.

    • settlement — settlement name.

    • date — timestamp of the status event.

The payload contains at least one tracking status. Each subsequent webhook delivery includes the newly added status and all previously delivered statuses.

Authorizations
AuthorizationstringRequired

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

Body
numbersstring[]Optional

Test shipment number always SHPL0000000001.

Example: ["SHPL0000000001"]
idstringOptional

The unique identifier for the created subscription.

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

Unique user identifier.

Example: 11a111a1-a1a1-11aa-a111-111111aa1111
Responses
200

Test webhook was sent successfully.

application/json
successstringOptional

Confirmation message about successful test.

Example: true
post/tracking-push/subscribers/test-webhook
POST /v.1.0/tracking-push/subscribers/test-webhook HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 119

{
  "numbers": [
    "SHPL0000000001"
  ],
  "id": "f5300824-58a9-496b-ac3b-bee156844fdf",
  "cid": "11a111a1-a1a1-11aa-a111-111111aa1111"
}
{
  "success": true
}
PreviousPickups
NextFullfillment

Last updated