> For the complete documentation index, see [llms.txt](https://api-portal.novapost.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://api-portal.novapost.com/methods/methods/webhooks/new-subscription.md). # New subscription ## 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.
```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.com/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","operationId":"createSubscriber","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","description":"The type of subscription to be created. This is a mandatory field and can take the following values:\n- `individual` — for personal accounts;\n- `numbers` — for tracking specific shipment numbers;\n- `legal` — for business accounts, requiring additional company details;\n- `recipientLegal` — tracks all shipments addressed to the specified legal recipient;\n- `creator` — tracks all shipments created by the client, regardless of whether they are specified as the sender.\n\nSee the [**Subscription types**](https://api-portal.novapost.com/methods/methods/webhooks/subscription-types) section.\n\n🔹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**](https://api-portal.novapost.com/methods/methods/webhooks/adding-numbers-to-a-subscription) method.\n","enum":["individual","numbers","legal","recipientLegal","creator"]},"url":{"type":"string","format":"uri","minLength":3,"description":"The callback URL where webhook notifications will be sent. The URL must be capable of receiving POST requests with JSON payloads.\n"},"isActive":{"type":"boolean","description":"Indicates whether the subscription should be active immediately upon creation. If `false`, the subscription is created but webhook notifications are not sent.\n"},"phone":{"type":"string","description":"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.\n\n**🔸Required when** `type` **is** `individual`.\n"},"eventTypes":{"type":"array","description":"A list of event types that the subscription will listen to. This parameter allows you to specify which events should trigger webhook notifications.\n\nIf no value is provided, the subscription is created for all event types by default.\n\nFor the allowed values, see the [**Event types for the eventTypes parameter**](https://api-portal.novapost.com/methods/methods/webhooks/event-types-and-tracking-status-codes) section.\n","items":{"type":"string"},"uniqueItems":true},"sendWarnings":{"type":"boolean","description":"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.\n","default":false},"warningEmail":{"type":"string","format":"email","description":"The email address where warnings about endpoint issues will be sent. The email address must be valid and active to ensure delivery of warnings.\n\n**🔸Required when** `sendWarnings` **is set to** `true`.\n"},"sendFullHistoryForMultiParcel":{"type":"boolean","description":"Defines how webhook notifications are sent for multi-parcel shipments.\n\n🔹If `true`, a separate webhook notification is sent for each parcel in the shipment. The request body structure remains unchanged.\n","default":false},"contentType":{"type":"string","description":"The Content-Type used for webhook requests. Supported values:\n- `application/json` — the recommended value for new integrations.\n- `text/plain` — a deprecated value whose support will be discontinued.\n\nThe selected value affects only the value of the `Content-Type` header. The structure of the request body is the same for both values.\n\n🔹If `contentType` is not provided, `application/json` is used by default.\n\n🔸`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.\n","enum":["application/json","text/plain"],"default":"application/json"},"companyTins":{"type":"array","description":"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.\n\n- 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`.\n- 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`.\n\n**🔸Required when** `type` **is** `legal` **or** `recipientLegal`.\n","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 Latin letters and digits, up to 600 characters.\n","minLength":0,"maxLength":600,"pattern":"^[A-Za-z0-9]+$"},"secretTokenHeaderName":{"type":"string","nullable":true,"description":"Header name 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 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](?:[A-Za-z0-9-]*[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.\n\n🔸**Save the** `id` **value — it is required for all further operations with this subscription.**\n"},"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]+$"},"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"},"url":{"type":"string","format":"uri","description":"The callback URL for the subscription."},"isActive":{"type":"boolean","description":"Indicates if the subscription is currently active."},"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.
\nAny values outside of this list are not supported and must not be provided.\n","items":{"type":"string"}},"sendWarnings":{"type":"boolean","description":"Indicates whether email warnings are sent for incorrect endpoint operations."},"warningEmail":{"type":"string","format":"email","description":"The email address used for sending warnings."},"sendFullHistoryForMultiParcel":{"type":"boolean","description":"Defines how webhook notifications are sent for multi-parcel shipments.\n\n🔹If `true`, a separate webhook notification is sent for each parcel in the shipment. The request body structure remains unchanged.\n","default":false},"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"}},"updatedAt":{"type":"string","format":"date-time","description":"The timestamp when the subscription was last updated."},"createdAt":{"type":"string","format":"date-time","description":"The timestamp when the subscription was created."}}}}}},"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"}}}} ``` ### 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 parameterUse instead
is_activeisActive
event_typeseventTypes
send_warningssendWarnings
warning_emailwarningEmail
company_tinscompanyTins
secret_tokensecretToken
secret_token_header_namesecretTokenHeaderName
created_atcreatedAt
updated_atupdatedAt
The same deprecated parameters are present in the responses to subscription creation and update. They are not repeated further in this article. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://api-portal.novapost.com/methods/methods/webhooks/new-subscription.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. 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.