# Webhooks ## Retrieve all subscriptions > Retrieve a list of all subscriptions associated with the client.\ > \ > 🔹\*\*Description of control elements:\*\*\ > \ > \*\*SCHEMA\*\*\
\ > Displays the full technical structure of the request or response, including field names, data types, required fields, allowed values, and validation rules.\ > \- \*\*Single line description\*\*\
\ > A description that fits into a single line; any text that does not fit remains hidden.\ > \- \*\*Multiline description\*\*\
\ > An expanded description that displays more than one line of text.\ > \ > \*\*EXAMPLE\*\*\
\ > Shows a ready-made sample JSON with correctly formatted values to demonstrate how a valid request or response should look.
```json {"openapi":"3.0.0","info":{"title":"API Nova Post","version":"1.0.0"},"tags":[{"name":"Webhooks"}],"servers":[{"description":"sandbox","url":"https://api-stage.novapost.pl/v.1.0/"},{"description":"production","url":"https://api.novapost.com/v.1.0/"}],"security":[{"JWT":[]}],"components":{"securitySchemes":{"JWT":{"type":"apiKey","in":"header","name":"Authorization","description":"Authorization JWT-token with a lifetime of 1 hour in header"}},"responses":{"Unauthorized":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"The specified resource was not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Validation":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Time-out":{"description":"Connection time-out","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"errors":{"type":"object","properties":{"":{"type":"string"}}}}}}},"paths":{"/tracking-push/subscribers":{"get":{"tags":["Webhooks"],"description":"Retrieve a list of all subscriptions associated with the client.\n\n🔹**Description of control elements:**\n\n**SCHEMA**
\nDisplays the full technical structure of the request or response, including field names, data types, required fields, allowed values, and validation rules.\n- **Single line description**
\n A description that fits into a single line; any text that does not fit remains hidden.\n- **Multiline description**
\n An expanded description that displays more than one line of text.\n\n**EXAMPLE**
\nShows a ready-made sample JSON with correctly formatted values to demonstrate how a valid request or response should look.\n","operationId":"getSubscribers","responses":{"200":{"description":"Successful response containing a list of subscriptions.","content":{"application/json":{"schema":{"type":"object","properties":{"current_page":{"type":"integer","description":"The current page of the paginated result set."},"last_page":{"type":"integer","description":"The last page of the paginated result set."},"per_page":{"type":"integer","description":"The number of items per page."},"total":{"type":"integer","description":"The total number of subscription items available."},"items":{"type":"array","description":"The array of subscription items.","items":{"type":"object","properties":{"id":{"type":"string","description":"The public identifier of the subscription."},"type":{"type":"string","description":"The type of subscription. Can be `individual`, `numbers`, `legal` or `creator`."},"url":{"type":"string","format":"uri","description":"The callback URL for the webhook notifications."},"isActive":{"type":"boolean","description":"Indicates if the subscription is currently active."},"is_active":{"type":"boolean","description":"Deprecated. Legacy field kept for backward compatibility. Use `isActive` instead."},"phone":{"type":"string","description":"The phone number associated with the subscription."},"cid":{"type":"string","description":"Unique user identifier"},"eventTypes":{"type":"array","description":"The list of event types the subscription is interested in.","items":{"type":"string"}},"event_types":{"type":"array","description":"Deprecated. Legacy field kept for backward compatibility. Use `eventTypes` instead.","items":{"type":"string"}},"sendWarnings":{"type":"boolean","description":"Indicates whether email warnings are sent for incorrect endpoint operations."},"send_warnings":{"type":"boolean","description":"Deprecated. Legacy field kept for backward compatibility. Use `sendWarnings` instead."},"warningEmail":{"type":"string","format":"email","description":"The email address used for sending warnings."},"warning_email":{"type":"string","format":"email","description":"Deprecated. Legacy field kept for backward compatibility. Use `warningEmail` instead."},"contentType":{"type":"string","description":"Specifies the content type used for webhook request payloads. The default value is `application/json`."},"companyTins":{"type":"array","description":"The list of company tax identification numbers of a legal entity associated with the subscription.","items":{"type":"string"}},"company_tins":{"type":"array","description":"Deprecated. Legacy field kept for backward compatibility. Use `companyTins` instead.","items":{"type":"string"}},"secretToken":{"type":"string","description":"Webhook authorization token used to validate incoming webhook requests.\n\n🔸The token is optional and, if provided, must consist only of alphanumeric characters.\n","minLength":0,"maxLength":600,"pattern":"^[A-Za-z0-9]+$"},"secret_token":{"type":"string","description":"Deprecated. Legacy field kept for backward compatibility. Use `secretToken` instead.","minLength":0,"maxLength":600,"pattern":"^[A-Za-z0-9]+$"},"secretTokenHeaderName":{"type":"string","description":"Header name used to transmit the `secretToken` in webhook requests.\n\nIf `secret_token_header_name` is provided and is not null, its value is used as the header name for transmitting the `secretToken`.
\nIf `secret_token_header_name` is not provided or is set to null, the default header name `X-NP-Key` is used.\n\n🔸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.\n"},"secret_token_header_name":{"type":"string","description":"Deprecated. Legacy field kept for backward compatibility. Use `secretTokenHeaderName` instead."},"updatedAt":{"type":"string","format":"datetime","description":"The timestamp when the subscription was last updated."},"updated_at":{"type":"string","format":"datetime","description":"Deprecated. Legacy field kept for backward compatibility. Use `updatedAt` instead."},"createdAt":{"type":"string","format":"datetime","description":"The timestamp when the subscription was created."},"created_at":{"type":"string","format":"datetime","description":"Deprecated. Legacy field kept for backward compatibility. Use `createdAt` instead."},"numbers":{"type":"array","description":"The list of tracking numbers associated with the subscription.","items":{"type":"string"}}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Validation"},"503":{"$ref":"#/components/responses/Time-out"}},"summary":"Retrieve all subscriptions"}}}} ``` ## 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 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.\ > \ > 🔹\*\*Description of control elements:\*\*\ > \ > \*\*SCHEMA\*\*\
\ > Displays the full technical structure of the request or response, including field names, data types, required fields, allowed values, and validation rules.\ > \- \*\*Single line description\*\*\
\ > A description that fits into a single line; any text that does not fit remains hidden.\ > \- \*\*Multiline description\*\*\
\ > An expanded description that displays more than one line of text.\ > \ > \*\*EXAMPLE\*\*\
\ > Shows a ready-made sample JSON with correctly formatted values to demonstrate how a valid request or response should look.
```json {"openapi":"3.0.0","info":{"title":"API Nova Post","version":"1.0.0"},"tags":[{"name":"Webhooks"}],"servers":[{"description":"sandbox","url":"https://api-stage.novapost.pl/v.1.0/"},{"description":"production","url":"https://api.novapost.com/v.1.0/"}],"security":[{"JWT":[]}],"components":{"securitySchemes":{"JWT":{"type":"apiKey","in":"header","name":"Authorization","description":"Authorization JWT-token with a lifetime of 1 hour in header"}},"responses":{"Unauthorized":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"The specified resource was not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Validation":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Time-out":{"description":"Connection time-out","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"errors":{"type":"object","properties":{"":{"type":"string"}}}}}}},"paths":{"/tracking-push/subscribers":{"post":{"tags":["Webhooks"],"description":"This endpoint is used to create a new subscription for receiving tracking notifications via webhooks.\nThe 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.\n\nWebhook notifications are sent using the `application/json` Content-Type by default.\n\n🔹**Description of control elements:**\n\n**SCHEMA**
\nDisplays the full technical structure of the request or response, including field names, data types, required fields, allowed values, and validation rules.\n- **Single line description**
\n A description that fits into a single line; any text that does not fit remains hidden.\n- **Multiline description**
\n An expanded description that displays more than one line of text.\n\n**EXAMPLE**
\nShows a ready-made sample JSON with correctly formatted values to demonstrate how a valid request or response should look.\n","operationId":"createSubscriber","parameters":[{"in":"query","name":"type","description":"The type of subscription to be created. This is a mandatory field and can take values such as:\n- **individual**: For personal accounts.\n- **numbers**: For tracking specific shipment numbers.\n- **legal**: For business accounts, requiring additional company details.\n- **creator**: To tracking all shipments created by the client, regardless of whether they are specified as the sender.\n","required":true,"schema":{"type":"string","enum":["individual","numbers","legal","creator"]}},{"in":"query","name":"url","description":"The callback URL where webhook notifications will be sent. \nThis is a mandatory field and must be a valid URL.\nThe URL should be capable of receiving POST requests with JSON payloads.\n","required":true,"schema":{"type":"string","format":"uri","minLength":3}},{"in":"query","name":"isActive","description":"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.","schema":{"type":"boolean","default":false},"required":true},{"in":"query","name":"phone","description":"The phone number associated with the subscription.\nThis parameter is required when the subscription type is `individual`.\nThe phone number must be in international format, for example, 380637445555.\n","required":false,"schema":{"type":"string"}},{"in":"query","name":"secretToken","description":"Webhook Authorization Token: Maximum Length 600 Characters\n","required":false,"schema":{"type":"string"}},{"in":"query","name":"secretTokenHeaderName","description":"Specifies the header name used to pass the `secretToken` in webhook requests.\n","required":false,"schema":{"type":"string"}},{"in":"query","name":"eventTypes","description":"A list of event types that the subscription will listen to. \nThis parameter allows you to specify which events should trigger webhook notifications. \nIf no value is provided, the subscription will be created for all event types by default.\n\nThe list of supported event types includes:\n- `ReadyToShip`: The shipment has been created and is ready for dispatch.\n- `Deleted`: The shipment has been deleted.\n- `ParcelPlaceRemoved`: A parcel has been removed from the shipment.\n- `Received`: The shipment has been received by the recipient.\n- `MoneyTransfer`: A money transfer related to the shipment has been created.\n- `MoneyTransferReceived`: The money transfer related to the shipment has been paid out to the recipient.\n- `Returned`: The shipment is being returned or has been returned to the sender.\n- `Refused`: The recipient has refused to accept the shipment.\n- `Redirecting`: The shipment is being redirected to another address or branch.\n- `Utilization`: The shipment has been disposed of.\n- `Redelivery`: A repeat delivery attempt for the shipment has been scheduled.\n- `UndeliveryReason`: A non-delivery reason has been recorded.\n- `ChangeTime`: The delivery date or time has been changed.\n- `ArrivalSC`: The shipment has arrived at the sorting center.\n- `TransferToPartner`: The shipment has been handed over to a partner for further delivery.\n- `LoadingCourier`: The shipment has been loaded onto the courier’s vehicle.\n- `ArrivalSenderWarehouse`: The shipment has arrived at the sender’s warehouse.\n- `DepartureSenderWarehouse`: The shipment has departed from the sender’s warehouse.\n- `InCityRecipient`: The shipment has arrived in the recipient’s city.\n- `AwaitingOnDivision`: The shipment is waiting at the branch or pickup point.\n\n🔸This field accepts **only** the event types listed above.
Any values outside of this list are not supported and must not be provided.\n","schema":{"type":"array","items":{"type":"string"},"uniqueItems":true},"required":false},{"in":"query","name":"sendWarnings","description":"Determines if email warnings should be sent in case of issues with the specified webhook URL.\nIf enabled, the system will send notifications about delivery problems or other errors.\nDefaults to `false`.\n","schema":{"type":"boolean","default":false},"required":false},{"in":"query","name":"warningEmail","description":"The email address where warnings about endpoint issues will be sent.\nIt is required if `sendWarnings` is set to `true`.\nThe email address should be valid and active to ensure delivery of warnings.\n","schema":{"type":"string","format":"email"},"required":false},{"in":"query","name":"companyTins","description":"A list of company tax identification numbers relevant to the subscription type `legal`.\nThis parameter is required for legal subscriptions and is essential to verify the company's identity.\nEach TIN should be a valid UUID.\n","schema":{"type":"array","items":{"type":"string","format":"uuid"}},"required":false}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","enum":["individual","numbers","legal","creator"],"description":"The type of subscription to be created."},"url":{"type":"string","format":"uri","description":"The callback URL where webhook notifications will be sent."},"isActive":{"type":"boolean","description":"Indicates whether the subscription is active immediately after creation."},"phone":{"type":"string","description":"The phone number associated with the subscription."},"eventTypes":{"type":"array","description":"A list of event types that the subscription will listen to.","items":{"type":"string"},"uniqueItems":true},"sendWarnings":{"type":"boolean","description":"Determines if email warnings should be sent for webhook delivery issues."},"warningEmail":{"type":"string","format":"email","description":"The email address where warnings will be sent."},"companyTins":{"type":"array","description":"A list of company tax identification numbers for legal subscriptions.","items":{"type":"string","format":"uuid"}},"secretToken":{"type":"string","description":"Webhook authorization token used to validate incoming webhook requests.\n\n🔸The token is optional and, if provided, must consist only of alphanumeric characters.\n","minLength":0,"maxLength":600,"pattern":"^[A-Za-z0-9]+$"},"secretTokenHeaderName":{"type":"string","description":"Specifies the name of the HTTP header used to transmit the `secretToken` in webhook requests.\n\nIf `secretTokenHeaderName` is provided and is not null, its value is used as the header name for transmitting the `secretToken`.
\nIf `secretTokenHeaderName` is not provided in the request, or is explicitly set to null, the default header name `X-NP-Key` is used.\n\nValidation requirements:\n- Only Latin letters, digits, and hyphens are allowed.\n- Must not start or end with a hyphen.\n- Must not contain spaces or any other special characters.\n\n**🔸This field is optional**\n","pattern":"A-Za-z0-9"}},"required":["type","url","isActive"]}}}},"responses":{"201":{"description":"Subscription successfully created.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the created subscription."},"type":{"type":"string","description":"The type of subscription created."},"secretToken":{"type":"string","description":"Webhook authorization token used to validate incoming webhook requests.\n\n🔸The token is optional and, if provided, must consist only of alphanumeric characters.\n","minLength":0,"maxLength":600,"pattern":"^[A-Za-z0-9]+$"},"secret_token":{"type":"string","description":"Deprecated. Legacy field kept for backward compatibility. Use `secretToken` instead.","minLength":0,"maxLength":600,"pattern":"^[A-Za-z0-9]+$"},"secretTokenHeaderName":{"type":"string","description":"Specifies the name of the HTTP header used to transmit the `secretToken` in webhook requests.\n\n🔸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.\n\n**🔸This field is optional**\n","pattern":"A-Za-z0-9"},"secret_token_header_name":{"type":"string","description":"Deprecated. Legacy field kept for backward compatibility. Use `secretTokenHeaderName` instead.","pattern":"A-Za-z0-9"},"url":{"type":"string","format":"uri","description":"The callback URL for the subscription."},"isActive":{"type":"boolean","description":"Indicates if the subscription is currently active."},"is_active":{"type":"boolean","description":"Deprecated. Legacy field kept for backward compatibility. Use `isActive` instead."},"phone":{"type":"string","description":"The phone number associated with the subscription."},"cid":{"type":"string","description":"Unique user identifier"},"eventTypes":{"type":"array","description":"The list of event types the subscription listens to:\n- `ReadyToShip`: The shipment has been created and is ready for dispatch.\n- `Deleted`: The shipment has been deleted.\n- `ParcelPlaceRemoved`: A parcel has been removed from the shipment.\n- `Received`: The shipment has been received by the recipient.\n- `MoneyTransfer`: A money transfer related to the shipment has been created.\n- `MoneyTransferReceived`: The money transfer related to the shipment has been paid out to the recipient.\n- `Returned`: The shipment is being returned or has been returned to the sender.\n- `Refused`: The recipient has refused to accept the shipment.\n- `Redirecting`: The shipment is being redirected to another address or branch.\n- `Utilization`: The shipment has been disposed of.\n- `Redelivery`: A repeat delivery attempt for the shipment has been scheduled.\n- `UndeliveryReason`: A non‑delivery reason has been recorded.\n- `ChangeTime`: The delivery date or time has been changed.\n- `ArrivalSC`: The shipment has arrived at the sorting center.\n- `TransferToPartner`: The shipment has been handed over to a partner for further delivery.\n- `LoadingCourier`: The shipment has been loaded onto the courier’s vehicle.\n- `ArrivalSenderWarehouse`: The shipment has arrived at the sender’s warehouse.\n- `DepartureSenderWarehouse`: The shipment has departed from the sender’s warehouse.\n- `InCityRecipient`: The shipment has arrived in the recipient’s city.\n- `AwaitingOnDivision`: The shipment is waiting at the branch or pickup point.\n\n🔸This field accepts **only** the event types listed above.
Any values outside of this list are not supported and must not be provided.\n","items":{"type":"string"}},"event_types":{"type":"array","description":"Deprecated. Legacy field kept for backward compatibility. Use `eventTypes` instead.","items":{"type":"string"}},"sendWarnings":{"type":"boolean","description":"Indicates whether email warnings are sent for incorrect endpoint operations."},"send_warnings":{"type":"boolean","description":"Deprecated. Legacy field kept for backward compatibility. Use `sendWarnings` instead."},"warningEmail":{"type":"string","format":"email","description":"The email address used for sending warnings."},"warning_email":{"type":"string","format":"email","description":"Deprecated. Legacy field kept for backward compatibility. Use `warningEmail` instead."},"contentType":{"type":"string","description":"Specifies the Content-Type used for webhook request payloads. The default value is `application/json`."},"companyTins":{"type":"array","description":"The list of company tax identification numbers of a legal entity associated with the subscription.","items":{"type":"string"}},"company_tins":{"type":"array","description":"Deprecated. Legacy field kept for backward compatibility. Use `companyTins` instead.","items":{"type":"string"}},"updatedAt":{"type":"string","format":"date-time","description":"The timestamp when the subscription was last updated."},"updated_at":{"type":"string","format":"date-time","description":"Deprecated. Legacy field kept for backward compatibility. Use `updatedAt` instead."},"createdAt":{"type":"string","format":"date-time","description":"The timestamp when the subscription was created."},"created_at":{"type":"string","format":"date-time","description":"Deprecated. Legacy field kept for backward compatibility. Use `createdAt` instead."}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Validation"},"503":{"$ref":"#/components/responses/Time-out"}},"summary":"Create a new subscription"}}}} ``` ## 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 essential for modifying subscription settings for clients who wish to manage how they receive tracking notifications.\ > \ > 🔹\*\*Description of control elements:\*\*\ > \ > \*\*SCHEMA\*\*\
\ > Displays the full technical structure of the request or response, including field names, data types, required fields, allowed values, and validation rules.\ > \- \*\*Single line description\*\*\
\ > A description that fits into a single line; any text that does not fit remains hidden.\ > \- \*\*Multiline description\*\*\
\ > An expanded description that displays more than one line of text.\ > \ > \*\*EXAMPLE\*\*\
\ > Shows a ready-made sample JSON with correctly formatted values to demonstrate how a valid request or response should look.
```json {"openapi":"3.0.0","info":{"title":"API Nova Post","version":"1.0.0"},"tags":[{"name":"Webhooks"}],"servers":[{"description":"sandbox","url":"https://api-stage.novapost.pl/v.1.0/"},{"description":"production","url":"https://api.novapost.com/v.1.0/"}],"security":[{"JWT":[]}],"components":{"securitySchemes":{"JWT":{"type":"apiKey","in":"header","name":"Authorization","description":"Authorization JWT-token with a lifetime of 1 hour in header"}},"responses":{"Unauthorized":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"The specified resource was not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Validation":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Time-out":{"description":"Connection time-out","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"errors":{"type":"object","properties":{"":{"type":"string"}}}}}}},"paths":{"/tracking-push/subscribers/{id}":{"put":{"tags":["Webhooks"],"description":"This endpoint updates an existing subscription's details such as the callback URL, activation status, event types, and more.\nIt is essential for modifying subscription settings for clients who wish to manage how they receive tracking notifications.\n\n🔹**Description of control elements:**\n\n**SCHEMA**
\nDisplays the full technical structure of the request or response, including field names, data types, required fields, allowed values, and validation rules.\n- **Single line description**
\n A description that fits into a single line; any text that does not fit remains hidden.\n- **Multiline description**
\n An expanded description that displays more than one line of text.\n\n**EXAMPLE**
\nShows a ready-made sample JSON with correctly formatted values to demonstrate how a valid request or response should look.\n","operationId":"updateSubscriber","parameters":[{"name":"id","in":"path","description":"The unique identifier of the subscription you want to update. This is a mandatory path parameter used to specify the subscription to be modified.","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"The payload containing the updated details for the subscription. Each field allows you to modify different aspects of the subscription.\n","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"The new callback URL for webhook notifications. This URL must be reachable and capable of handling POST requests.\n"},"isActive":{"type":"boolean","description":"Specifies whether the subscription is currently active. Set to `true` to activate the subscription, or `false` to deactivate it.\n"},"type":{"type":"string","description":"The type of subscription created. \n"},"eventTypes":{"type":"array","description":"A list of event types that the subscription will listen for. You can specify which events should trigger webhook notifications.\n","items":{"type":"string"}},"sendWarnings":{"type":"boolean","description":"Indicates if the system should send email warnings about issues with the specified webhook URL. Set to `true` to enable warnings.\n"},"warningEmail":{"type":"string","format":"email","description":"The email address for sending warnings. This field is necessary if `sendWarnings` is set to `true`.\n"},"secretToken":{"type":"string","description":"Webhook authorization token used to validate incoming webhook requests.\n\n🔸The token is optional and, if provided, must consist only of alphanumeric characters.\n","minLength":0,"maxLength":600,"pattern":"^[A-Za-z0-9]+$"},"secretTokenHeaderName":{"type":"string","description":"Specifies the name of the HTTP header used to transmit the `secretToken` in webhook requests.\n\nIf `secretTokenHeaderName` is provided and is not null, its value is used as the header name for transmitting the `secretToken`.
\nIf `secretTokenHeaderName` is not provided in the request, or is explicitly set to null, the default header name `X-NP-Key` is used.\n\nValidation requirements:\n- Only Latin letters, digits, and hyphens are allowed.\n- Must not start or end with a hyphen.\n- Must not contain spaces or any other special characters.\n\n**🔸This field is optional**\n","pattern":"A-Za-z0-9"}},"required":["id","url","isActive"]}}}},"responses":{"200":{"description":"Subscription successfully updated.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the updated subscription."},"type":{"type":"string","description":"The subscription type, such as `individual`, `numbers`, or `legal`."},"url":{"type":"string","format":"uri","description":"The updated callback URL for the subscription."},"isActive":{"type":"boolean","description":"Indicates if the subscription is currently active."},"is_active":{"type":"boolean","description":"Deprecated. Legacy field kept for backward compatibility. Use `isActive` instead."},"phone":{"type":"string","description":"The phone number associated with the subscription, if applicable."},"cid":{"type":"string","description":"Unique user identifier"},"eventTypes":{"type":"array","description":"A list of event types the subscription listens to.","items":{"type":"string"}},"event_types":{"type":"array","description":"Deprecated. Legacy field kept for backward compatibility. Use `eventTypes` instead.","items":{"type":"string"}},"sendWarnings":{"type":"boolean","description":"Indicates whether email warnings are sent for incorrect endpoint operations."},"send_warnings":{"type":"boolean","description":"Deprecated. Legacy field kept for backward compatibility. Use `sendWarnings` instead."},"warningEmail":{"type":"string","format":"email","description":"The email address used for sending warnings."},"warning_email":{"type":"string","format":"email","description":"Deprecated. Legacy field kept for backward compatibility. Use `warningEmail` instead."},"contentType":{"type":"string","description":"Specifies the Content-Type used for webhook request payloads.\n\nThe default value is `application/json`.\n"},"companyTins":{"type":"array","description":"The list of company tax identification numbers of a legal entity associated with the subscription.","items":{"type":"string"}},"company_tins":{"type":"array","description":"Deprecated. Legacy field kept for backward compatibility. Use `companyTins` instead.","items":{"type":"string"}},"secretToken":{"type":"string","description":"Webhook authorization token used to validate incoming webhook requests.\n\n🔸The token is optional and, if provided, must consist only of alphanumeric characters.\n","minLength":0,"maxLength":600,"pattern":"^[A-Za-z0-9]+$"},"secret_token":{"type":"string","description":"Deprecated. Legacy field kept for backward compatibility. Use `secretToken` instead.","minLength":0,"maxLength":600,"pattern":"^[A-Za-z0-9]+$"},"secretTokenHeaderName":{"type":"string","description":"Specifies the name of the HTTP header used to transmit the `secretToken` in webhook requests.\n\n🔸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.\n","pattern":"A-Za-z0-9"},"secret_token_header_name":{"type":"string","description":"Deprecated. Legacy field kept for backward compatibility. Use `secretTokenHeaderName` instead."},"updatedAt":{"type":"string","format":"date-time","description":"The timestamp when the subscription was last updated."},"updated_at":{"type":"string","format":"date-time","description":"Deprecated. Legacy field kept for backward compatibility. Use `updatedAt` instead."},"createdAt":{"type":"string","format":"date-time","description":"The timestamp when the subscription was created."},"created_at":{"type":"string","format":"date-time","description":"Deprecated. Legacy field kept for backward compatibility. Use `createdAt` instead."}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Validation"},"503":{"$ref":"#/components/responses/Time-out"}},"summary":"Update an existing subscription"}}}} ``` ## Delete a subscription > 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.\ > \ > 🔹\*\*Description of control elements:\*\*\ > \ > \*\*SCHEMA\*\*\
\ > Displays the full technical structure of the request or response, including field names, data types, required fields, allowed values, and validation rules.\ > \- \*\*Single line description\*\*\
\ > A description that fits into a single line; any text that does not fit remains hidden.\ > \- \*\*Multiline description\*\*\
\ > An expanded description that displays more than one line of text.\ > \ > \*\*EXAMPLE\*\*\
\ > Shows a ready-made sample JSON with correctly formatted values to demonstrate how a valid request or response should look.
```json {"openapi":"3.0.0","info":{"title":"API Nova Post","version":"1.0.0"},"tags":[{"name":"Webhooks"}],"servers":[{"description":"sandbox","url":"https://api-stage.novapost.pl/v.1.0/"},{"description":"production","url":"https://api.novapost.com/v.1.0/"}],"security":[{"JWT":[]}],"components":{"securitySchemes":{"JWT":{"type":"apiKey","in":"header","name":"Authorization","description":"Authorization JWT-token with a lifetime of 1 hour in header"}},"responses":{"Unauthorized":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"The specified resource was not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Validation":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Time-out":{"description":"Connection time-out","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"errors":{"type":"object","properties":{"":{"type":"string"}}}}}}},"paths":{"/tracking-push/subscribers/{id}":{"delete":{"tags":["Webhooks"],"description":"This endpoint deletes a subscription specified by its unique identifier. Once deleted, the subscription will no longer receive webhook notifications.\nThe deletion is irreversible and should be used with caution.\n\n🔹**Description of control elements:**\n\n**SCHEMA**
\nDisplays the full technical structure of the request or response, including field names, data types, required fields, allowed values, and validation rules.\n- **Single line description**
\n A description that fits into a single line; any text that does not fit remains hidden.\n- **Multiline description**
\n An expanded description that displays more than one line of text.\n\n**EXAMPLE**
\nShows a ready-made sample JSON with correctly formatted values to demonstrate how a valid request or response should look.\n","operationId":"deleteSubscriber","parameters":[{"name":"id","in":"path","description":"The unique identifier of the subscription to be deleted. This is a required path parameter that identifies the specific subscription you wish to remove.\n","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Subscription successfully deleted.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"A confirmation message indicating successful deletion of the subscription."}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Validation"},"503":{"$ref":"#/components/responses/Time-out"}},"summary":"Delete a subscription"}}}} ``` ## Add numbers to an existing subscription > 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.\ > \ > 🔹\*\*Description of control elements:\*\*\ > \ > \*\*SCHEMA\*\*\
\ > Displays the full technical structure of the request or response, including field names, data types, required fields, allowed values, and validation rules.\ > \- \*\*Single line description\*\*\
\ > A description that fits into a single line; any text that does not fit remains hidden.\ > \- \*\*Multiline description\*\*\
\ > An expanded description that displays more than one line of text.\ > \ > \*\*EXAMPLE\*\*\
\ > Shows a ready-made sample JSON with correctly formatted values to demonstrate how a valid request or response should look.
```json {"openapi":"3.0.0","info":{"title":"API Nova Post","version":"1.0.0"},"tags":[{"name":"Webhooks"}],"servers":[{"description":"sandbox","url":"https://api-stage.novapost.pl/v.1.0/"},{"description":"production","url":"https://api.novapost.com/v.1.0/"}],"security":[{"JWT":[]}],"components":{"securitySchemes":{"JWT":{"type":"apiKey","in":"header","name":"Authorization","description":"Authorization JWT-token with a lifetime of 1 hour in header"}},"responses":{"Unauthorized":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"The specified resource was not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Validation":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Time-out":{"description":"Connection time-out","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"errors":{"type":"object","properties":{"":{"type":"string"}}}}}}},"paths":{"/tracking-push/subscribers/{id}/numbers":{"post":{"summary":"Add numbers to an existing subscription","description":"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.\n\n🔹**Description of control elements:**\n\n**SCHEMA**
\nDisplays the full technical structure of the request or response, including field names, data types, required fields, allowed values, and validation rules.\n- **Single line description**
\n A description that fits into a single line; any text that does not fit remains hidden.\n- **Multiline description**
\n An expanded description that displays more than one line of text.\n\n**EXAMPLE**
\nShows a ready-made sample JSON with correctly formatted values to demonstrate how a valid request or response should look.\n","operationId":"addNumbersToSubscriber","tags":["Webhooks"],"parameters":[{"name":"id","in":"path","description":"The unique identifier of the subscription to which shipment numbers will be added. This is a required path parameter.\n","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"The payload containing the list of shipment numbers to be added to the subscription. The subscription type must be `numbers` for this operation to be valid.\n","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"numbers":{"type":"array","description":"A list of shipment numbers to be added to the subscription.","items":{"type":"string"}}}}}}},"responses":{"200":{"description":"Numbers successfully added to the subscription.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"A confirmation message indicating successful addition of numbers."},"addedNumbers":{"type":"array","description":"The list of numbers that were successfully added to the subscription.","items":{"type":"string"}},"missedNumbers":{"type":"array","description":"The list of numbers that could not be added (e.g., invalid or already linked).","items":{"type":"string"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Validation"},"503":{"$ref":"#/components/responses/Time-out"}}}}}} ``` ## Delete numbers from an existing subscription > This endpoint allows deleted shipment numbers from an existing subscription specified by its unique identifier.\ > \ > 🔹\*\*Description of control elements:\*\*\ > \ > \*\*SCHEMA\*\*\
\ > Displays the full technical structure of the request or response, including field names, data types, required fields, allowed values, and validation rules.\ > \- \*\*Single line description\*\*\
\ > A description that fits into a single line; any text that does not fit remains hidden.\ > \- \*\*Multiline description\*\*\
\ > An expanded description that displays more than one line of text.\ > \ > \*\*EXAMPLE\*\*\
\ > Shows a ready-made sample JSON with correctly formatted values to demonstrate how a valid request or response should look.
```json {"openapi":"3.0.0","info":{"title":"API Nova Post","version":"1.0.0"},"tags":[{"name":"Webhooks"}],"servers":[{"description":"sandbox","url":"https://api-stage.novapost.pl/v.1.0/"},{"description":"production","url":"https://api.novapost.com/v.1.0/"}],"security":[{"JWT":[]}],"components":{"securitySchemes":{"JWT":{"type":"apiKey","in":"header","name":"Authorization","description":"Authorization JWT-token with a lifetime of 1 hour in header"}},"responses":{"Unauthorized":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"The specified resource was not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Validation":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Time-out":{"description":"Connection time-out","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"errors":{"type":"object","properties":{"":{"type":"string"}}}}}}},"paths":{"/tracking-push/subscribers/{id}/numbers":{"delete":{"summary":"Delete numbers from an existing subscription","description":"This endpoint allows deleted shipment numbers from an existing subscription specified by its unique identifier.\n\n🔹**Description of control elements:**\n\n**SCHEMA**
\nDisplays the full technical structure of the request or response, including field names, data types, required fields, allowed values, and validation rules.\n- **Single line description**
\n A description that fits into a single line; any text that does not fit remains hidden.\n- **Multiline description**
\n An expanded description that displays more than one line of text.\n\n**EXAMPLE**
\nShows a ready-made sample JSON with correctly formatted values to demonstrate how a valid request or response should look.\n","operationId":"deleteNumbersToSubscriber","tags":["Webhooks"],"parameters":[{"name":"id","in":"path","description":"The unique identifier of the subscription to which shipment numbers will be deleted. This is a required path parameter.\n","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"The payload containing the list of shipment numbers to be deleted from the subscription. The subscription type must be `numbers` for this operation to be valid.\n","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"numbers":{"type":"array","description":"A list of shipment numbers to be deleted to the subscription.","items":{"type":"string"}}}}}}},"responses":{"200":{"description":"Numbers successfully deleted with subscription.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"A confirmation message indicating successful deleted of numbers."}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Validation"},"503":{"$ref":"#/components/responses/Time-out"}}}}}} ``` ## Checking the 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:\ > \`\`\`json\ > {\ > "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 \`statusCode\` parameter in the response of the \\FullTracking\\ method, under the \*\*SCHEMA\*\* tab in the \*\*Multiline description\*\*.\ > \- \`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.\ > \ > 🔹\*\*Description of control elements:\*\*\ > \ > \*\*SCHEMA\*\*\
\ > Displays the full technical structure of the request or response, including field names, data types, required fields, allowed values, and validation rules.\ > \- \*\*Single line description\*\*\
\ > A description that fits into a single line; any text that does not fit remains hidden.\ > \- \*\*Multiline description\*\*\
\ > An expanded description that displays more than one line of text.\ > \ > \*\*EXAMPLE\*\*\
\ > Shows a ready-made sample JSON with correctly formatted values to demonstrate how a valid request or response should look.
````json {"openapi":"3.0.0","info":{"title":"API Nova Post","version":"1.0.0"},"tags":[{"name":"Webhooks"}],"servers":[{"description":"sandbox","url":"https://api-stage.novapost.pl/v.1.0/"},{"description":"production","url":"https://api.novapost.com/v.1.0/"}],"security":[{"JWT":[]}],"components":{"securitySchemes":{"JWT":{"type":"apiKey","in":"header","name":"Authorization","description":"Authorization JWT-token with a lifetime of 1 hour in header"}},"responses":{"Unauthorized":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"The specified resource was not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Validation":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Time-out":{"description":"Connection time-out","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"errors":{"type":"object","properties":{"":{"type":"string"}}}}}}},"paths":{"/tracking-push/subscribers/test-webhook":{"post":{"summary":"Checking the test webhook","description":"This endpoint allows you to test the webhook functionality. At least one active subscription is required for a successful response.\n\nWebhook requests are sent using the `application/json` Content-Type by default.\n\n🔹**Test webhook behavior:**
\nThe method returns a confirmation response indicating that a test webhook request was sent.\nA webhook event with tracking data is delivered to the subscriber endpoint.\n\n🔹**Webhook payload parameters:**
\nThe webhook request body looks as follows:\n```json\n{\n \"number\": \"SHPL0000000001\",\n \"scheduled_delivery_date\": \"2024-11-20T20:03:00.000000Z\",\n \"history_tracking\": [\n {\n \"code\": \"4\",\n \"code_name\": \"On the way\",\n \"country_code\": \"UA\",\n \"settlement\": \"Kyiv\",\n \"date\": \"2024-11-19T09:32:05.000000Z\"\n },\n {\n \"code\": \"112\",\n \"code_name\": \"Change of delivery date\",\n \"country_code\": \"\",\n \"settlement\": \"\",\n \"date\": \"2024-11-19T09:33:56.000000Z\"\n }\n ]\n}\n```\nwith the following parameters:\n- `number` — shipment number.\n- `scheduled_delivery_date` — scheduled delivery date and time in ISO 8601 format.\n- `history_tracking` — array of tracking status objects.\n - `code` — tracking status code.
For more details about tracking status codes, see the description of the `statusCode` parameter in the response of the FullTracking method, under the **SCHEMA** tab in the **Multiline description**.\n - `code_name` — tracking status name.\n - `country_code` — country code where the status was recorded.\n - `settlement` — settlement name.\n - `date` — timestamp of the status event.\n\nThe payload contains at least one tracking status.
\nEach subsequent webhook delivery includes the newly added status and all previously delivered statuses.\n\n🔹**Description of control elements:**\n\n**SCHEMA**
\nDisplays the full technical structure of the request or response, including field names, data types, required fields, allowed values, and validation rules.\n- **Single line description**
\n A description that fits into a single line; any text that does not fit remains hidden.\n- **Multiline description**
\n An expanded description that displays more than one line of text.\n\n**EXAMPLE**
\nShows a ready-made sample JSON with correctly formatted values to demonstrate how a valid request or response should look.\n","operationId":"testWebhook","tags":["Webhooks"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"numbers":{"type":"array","description":"Test shipment number always SHPL0000000001","items":{"type":"string"}},"id":{"type":"string","description":"The unique identifier for the created subscription."},"cid":{"type":"string","description":"Unique user identifier"}}}}}},"responses":{"200":{"description":"Test webhook was sent successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"string","description":"Confirmation message about successful test"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Validation"},"503":{"$ref":"#/components/responses/Time-out"}}}}}} ```` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://api-portal.novapost.com/metodi-1/methods/webhooks.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.