> 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/ua/overview/webhooks/subscription-update.md). # Оновлення підписки ## Оновити існуючу підписку > Цей метод оновлює дані існуючої підписки, зокрема callback URL, статус активності, типи подій тощо.\ > \ > Він використовується для зміни налаштувань підписки клієнтами, які хочуть керувати способом отримання сповіщень про відстеження.\ > \ > \*\*Метод виконує повну заміну налаштувань, а не часткове оновлення\*\*. Параметри, які ви не передасте, буде скинуто. Наприклад, якщо змінити лише \`url\`, підписка втратить фільтр \`eventTypes\` і почне отримувати webhook-сповіщення за всіма подіями. Завжди передавайте повний набір параметрів, навіть якщо змінюєте один із них.\ > \ > \*\*Тип підписки змінити не можна\*\*. Якщо передати в запиті параметр type з іншим значенням, зміна не застосується. Щоб перейти на інший тип, створіть нову підписку й видаліть стару. \ > \ > \*\*Зверніть увагу\*\*: події, що відбудуться за час, поки підписка вимкнена, після її повторного ввімкнення не надійдуть.
```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":"Авторизаційний JWT-токен із терміном дії 1 година в заголовку"}},"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":"Цей метод оновлює дані існуючої підписки, зокрема callback URL, статус активності, типи подій тощо.\n\nВін використовується для зміни налаштувань підписки клієнтами, які хочуть керувати способом отримання сповіщень про відстеження.\n\n**Метод виконує повну заміну налаштувань, а не часткове оновлення**. Параметри, які ви не передасте, буде скинуто. Наприклад, якщо змінити лише `url`, підписка втратить фільтр `eventTypes` і почне отримувати webhook-сповіщення за всіма подіями. Завжди передавайте повний набір параметрів, навіть якщо змінюєте один із них.\n\n**Тип підписки змінити не можна**. Якщо передати в запиті параметр type з іншим значенням, зміна не застосується. Щоб перейти на інший тип, створіть нову підписку й видаліть стару. \n\n**Зверніть увагу**: події, що відбудуться за час, поки підписка вимкнена, після її повторного ввімкнення не надійдуть.\n","operationId":"updateSubscriber","parameters":[{"name":"id","in":"path","description":"Унікальний ідентифікатор підписки, яку необхідно оновити. Це обов’язковий параметр шляху, який використовується для визначення підписки, що буде змінена.","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"Тіло запиту, що містить оновлені дані підписки. Кожне поле дозволяє змінювати різні параметри підписки.","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"Нова URL-адреса зворотного виклику для webhook-сповіщень. Цей URL повинен бути доступним і підтримувати обробку POST-запитів."},"isActive":{"type":"boolean","description":"Визначає, чи є підписка наразі активною. Встановіть значення `true`, щоб активувати підписку, або `false`, щоб деактивувати її."},"eventTypes":{"type":"array","description":"Список типів подій, які буде відстежувати підписка. Цей параметр дозволяє визначити, які події повинні ініціювати webhook-сповіщення.\n\nЯкщо параметр не передано, фільтр буде скинуто й надходитимуть усі підтримувані події.\n\nДопустимі значення — див. розділ [**Типи подій для параметра eventTypes**](https://api-portal.novapost.com/methods/ua/overview/webhooks/event-types-and-tracking-status-codes).\n","items":{"type":"string"}},"sendWarnings":{"type":"boolean","description":"Визначає, чи надсилати листи в разі проблем із доставкою webhook-сповіщень. Встановіть значення `true`, щоб увімкнути надсилання попереджень."},"warningEmail":{"type":"string","format":"email","description":"Адреса електронної пошти для надсилання попереджень. Це поле є необхідним, якщо параметр `sendWarnings` має значення `true`."},"companyTins":{"type":"array","description":"Список податкових ідентифікаційних номерів компаній, що використовуються для типу підписок `legal` або `recipientLegal`.\n\n- Для `legal` підписка отримує події лише для відправлень, у яких значення поля `sender.companyTin` збігається з одним із значень, переданих у полі `companyTins`.\n- Для `recipientLegal` підписка отримує події лише для відправлень, у яких значення поля `recipient.companyTin` збігається з одним із значень, переданих у полі `companyTins`.\n","items":{"type":"string","format":"uuid"}},"sendFullHistoryForMultiParcel":{"type":"boolean","description":"Визначає спосіб надсилання webhook-сповіщень для багатомісцевих відправлень.\n\n🔹Якщо `true`, webhook-сповіщення надсилається окремо по кожному місцю відправлення. Структура тіла запиту при цьому не змінюється.\n\n🔹За замовчуванням — `false`.\n","default":false},"contentType":{"type":"string","description":"Content-Type, з яким надсилатимуться webhook-запити. Підтримувані значення:\n- `application/json` — рекомендоване значення для нових інтеграцій.\n- `text/plain` — застаріле значення, підтримку якого буде припинено.\n\nВибране значення впливає лише на значення заголовка `Content-Type`. Структура тіла запиту однакова для обох значень.\n\n🔹Якщо `contentType` не передано, за замовчуванням використовується `application/json`.\n\n🔸`text/plain` — застаріле значення, підтримку якого буде припинено. Для нових інтеграцій використовуйте `application/json`. Якщо ваша підписка наразі використовує `text/plain`, рекомендуємо перейти на `application/json` завчасно: тіло запиту при цьому не зміниться, зміниться лише значення заголовка `Content-Type`.\n","enum":["application/json","text/plain"],"default":"application/json"},"secretToken":{"type":"string","description":"Токен авторизації webhook, який використовується для перевірки вхідних webhook-запитів.\n\n🔸Токен є необов’язковим і, якщо його надано, повинен містити лише латинські літери та цифри, до 600 символів.\n","minLength":0,"maxLength":600,"pattern":"^[A-Za-z0-9]+$"},"secretTokenHeaderName":{"type":"string","nullable":true,"description":"Назва заголовка, що використовується для передачі `secretToken` у webhook-запитах.\n\nЯкщо `secretTokenHeaderName` передано та його значення не є null, його значення використовується як назва заголовка для передачі `secretToken`.
\nЯкщо `secretTokenHeaderName` не передано або встановлено значення `null`, використовується назва заголовка за замовчуванням `X-NP-Key`.\n\nВимоги до валідації:\n- Дозволені лише латинські літери, цифри та дефіси.\n- Не повинен починатися або закінчуватися дефісом.\n- Не повинен містити пробіли або будь-які інші спеціальні символи.\n\n**🔸Це поле є необов’язковим.**\n","pattern":"^[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?$"}},"required":["url","isActive"]}}}},"responses":{"200":{"description":"Підписку успішно оновлено.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Унікальний ідентифікатор оновленої підписки."},"type":{"type":"string","description":"Тип підписки, наприклад `individual`, `numbers` або `legal`."},"url":{"type":"string","format":"uri","description":"Оновлений URL зворотного виклику для підписки."},"isActive":{"type":"boolean","description":"Визначає, чи є підписка наразі активною."},"phone":{"type":"string","description":"Номер телефону, пов’язаний із підпискою, якщо застосовно."},"cid":{"type":"string","description":"Унікальний ідентифікатор користувача."},"eventTypes":{"type":"array","description":"Список типів подій, які буде відстежувати підписка.","items":{"type":"string"}},"sendWarnings":{"type":"boolean","description":"Визначає, чи надсилаються попередження електронною поштою у разі некоректної роботи методу."},"warningEmail":{"type":"string","format":"email","description":"Адреса електронної пошти, яка використовується для надсилання попереджень."},"contentType":{"type":"string","description":"Визначає Content-Type, який використовується для тіла webhook-запитів.\n\nЗначення за замовчуванням — `application/json`.\n"},"companyTins":{"type":"array","description":"Список податкових ідентифікаційних номерів юридичної особи, пов’язаної з підпискою.\n","items":{"type":"string"}},"secretToken":{"type":"string","description":"Токен авторизації webhook, який використовується для перевірки вхідних webhook-запитів.\n\n🔸Токен є необов’язковим і, якщо його надано, повинен містити лише літерно-цифрові символи.\n","minLength":0,"maxLength":600,"pattern":"^[A-Za-z0-9]+$"},"secretTokenHeaderName":{"type":"string","description":"Визначає назву HTTP-заголовка, який використовується для передачі `secretToken` у webhook-запитах.\n\n🔸Це поле є необов’язковим і, якщо його вказано, повинно містити лише латинські літери, цифри та дефіси, не повинно починатися або закінчуватися дефісом, а також не повинно містити пробіли чи інші спеціальні символи.\n","pattern":"A-Za-z0-9"},"updatedAt":{"type":"string","format":"date-time","description":"Дата та час останнього оновлення підписки."},"createdAt":{"type":"string","format":"date-time","description":"Дата та час створення підписки."}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Validation"},"503":{"$ref":"#/components/responses/Time-out"}},"summary":"Оновити існуючу підписку"}}}} ``` ### Застарілі параметри Частина параметрів дублюється у `snake_case`-написанні. Ці параметри збережено виключно для забезпечення зворотної сумісності — для нових інтеграцій використовуйте варіанти в `camelCase`.
Застарілий параметрВикористовуйте замість нього
is_activeisActive
event_typeseventTypes
send_warningssendWarnings
warning_emailwarningEmail
company_tinscompanyTins
secret_tokensecretToken
secret_token_header_namesecretTokenHeaderName
created_atcreatedAt
updated_atupdatedAt
Ці ж застарілі параметри присутні у відповідях на створення та оновлення підписки. Далі в статті вони не повторюються. --- # 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 dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://api-portal.novapost.com/methods/ua/overview/webhooks/subscription-update.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.