> 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/subscription-update.md). # Subscription update ## 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.\ > \ > \*\*This endpoint performs a full replacement of the settings, not a partial update\*\*. Parameters that you do not pass are reset. For example, if you change only \`url\`, the subscription loses its \`eventTypes filter\` and starts receiving webhook notifications for all events. Always pass the full set of parameters, even if you change only one of them.\ > \ > \*\*The subscription type cannot be changed\*\*. If you pass the type parameter with a different value in the request, the change is not applied. To switch to another type, create a new subscription and delete the old one.\ > \ > \*\*Please note\*\*: events that occur while the subscription is disabled are not delivered after it is enabled again.
```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/{id}":{"put":{"tags":["Webhooks"],"description":"This endpoint updates an existing subscription's details such as the callback URL, activation status, event types, and more.\n\nIt is essential for modifying subscription settings for clients who wish to manage how they receive tracking notifications.\n\n**This endpoint performs a full replacement of the settings, not a partial update**. Parameters that you do not pass are reset. For example, if you change only `url`, the subscription loses its `eventTypes filter` and starts receiving webhook notifications for all events. Always pass the full set of parameters, even if you change only one of them.\n\n**The subscription type cannot be changed**. If you pass the type parameter with a different value in the request, the change is not applied. To switch to another type, create a new subscription and delete the old one.\n\n**Please note**: events that occur while the subscription is disabled are not delivered after it is enabled again.\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.","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."},"isActive":{"type":"boolean","description":"Specifies whether the subscription is currently active. Set to `true` to activate the subscription, or `false` to deactivate it."},"eventTypes":{"type":"array","description":"A list of event types that the subscription will listen for. This parameter allows you to specify which events should trigger webhook notifications.\n\nIf the parameter is not passed, the filter is reset and all supported events are sent.\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"}},"sendWarnings":{"type":"boolean","description":"Indicates if the system should send email warnings about issues with the delivery of webhook notifications. Set to `true` to enable warnings."},"warningEmail":{"type":"string","format":"email","description":"The email address for sending warnings. This field is necessary if `sendWarnings` is set to `true`."},"companyTins":{"type":"array","description":"A list of company tax identification numbers relevant to subscriptions of type `legal` or `recipientLegal`.\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","items":{"type":"string","format":"uuid"}},"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"},"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":["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."},"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"}},"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.\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.\n","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]+$"},"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"},"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":"Update an existing 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/subscription-update.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.