> 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/new-subscription.md).
# Нова підписка
## Створити нову підписку
> Цей метод використовується для створення нової підписки для отримання сповіщень про відстеження через webhook.\
> Підписка може бути різних типів, наприклад для окремого номера або для компанії, і є необхідною для клієнтів, які хочуть отримувати оновлення статусів відправлень у реальному часі.
```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":{"post":{"tags":["Webhooks"],"description":"Цей метод використовується для створення нової підписки для отримання сповіщень про відстеження через webhook.\nПідписка може бути різних типів, наприклад для окремого номера або для компанії, і є необхідною для клієнтів, які хочуть отримувати оновлення статусів відправлень у реальному часі.\n","operationId":"createSubscriber","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","description":"Тип підписки, яку необхідно створити. Це обов’язкове поле, яке може приймати такі значення:\n- `individual` — для особистих облікових записів;\n- `numbers` — для відстеження конкретних номерів відправлень;\n- `legal` — для бізнес-облікових записів, що потребують додаткових даних про компанію;\n- `recipientLegal` — для відстеження всіх відправлень, що прямують до юридичного клієнта-одержувача;\n- `creator` — для відстеження всіх відправлень, створених клієнтом, незалежно від того, чи вказаний він як відправник.\n\nДив. розділ [**Типи підписок**](https://api-portal.novapost.com/methods/ua/overview/webhooks/subscription-types).\n\n🔹Номери відправлень під час створення підписки не передаються. Для підписки типу `numbers` спочатку створіть підписку, а потім додайте номери окремим запитом — див. метод [**Додати номери до існуючої підписки**](https://api-portal.novapost.com/methods/ua/overview/webhooks/adding-numbers-to-a-subscription).\n","enum":["individual","numbers","legal","recipientLegal","creator"]},"url":{"type":"string","format":"uri","minLength":3,"description":"URL зворотного виклику, на який надсилатимуться webhook-сповіщення. Має підтримувати отримання POST-запитів із JSON-навантаженням.\n"},"isActive":{"type":"boolean","description":"Визначає, чи повинна підписка бути активною одразу після створення. Якщо `false`, підписку буде створено, але webhook-сповіщення не надсилатимуться.\n"},"phone":{"type":"string","description":"Номер телефону, пов’язаний із підпискою. Номер телефону повинен бути в міжнародному форматі.\n\n**🔸Обов’язкове, якщо** `type` **має значення** `individual`.\n"},"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"},"uniqueItems":true},"sendWarnings":{"type":"boolean","description":"Визначає, чи потрібно надсилати попередження електронною поштою у разі виникнення проблем із зазначеним webhook URL. Якщо параметр увімкнено, система надсилатиме сповіщення про проблеми доставки або інші помилки.\n\n🔹За замовчуванням використовується значення `false`.\n","default":false},"warningEmail":{"type":"string","format":"email","description":"Адреса електронної пошти, на яку надсилатимуться попередження щодо проблем із методом. Адреса електронної пошти повинна бути коректною та активною для забезпечення доставки попереджень.\n\n**🔸Обов’язкове, якщо** `sendWarnings` **має значення** `true`.\n"},"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"},"companyTins":{"type":"array","description":"Список податкових ідентифікаційних номерів компаній, що використовуються для типу підписок `legal` або `recipientLegal`. Цей параметр є обов’язковим для юридичних підписок і необхідний для підтвердження особи компанії. Кожен TIN повинен бути коректним UUID.\n\n- Для `legal` підписка отримує події лише для відправлень, у яких значення поля `sender.companyTin` збігається з одним із значень, переданих у полі `companyTins`.\n- Для `recipientLegal` підписка отримує події лише для відправлень, у яких значення поля `recipient.companyTin` збігається з одним із значень, переданих у полі `companyTins`.\n\n**🔸Обов’язкове, якщо** `type` **має значення** `legal` **або** `recipientLegal`.\n","items":{"type":"string","format":"uuid"}},"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":["type","url","isActive"]}}}},"responses":{"201":{"description":"Підписку успішно створено.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Унікальний ідентифікатор створеної підписки.\n\n🔸**Збережіть значення** `id` **— воно необхідне для всіх подальших операцій із цією підпискою.**\n"},"type":{"type":"string","description":"Тип створеної підписки."},"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\n**🔸Це поле є необов’язковим.**\n","pattern":"A-Za-z0-9"},"url":{"type":"string","format":"uri","description":"URL зворотного виклику для підписки."},"isActive":{"type":"boolean","description":"Визначає, чи є підписка наразі активною."},"phone":{"type":"string","description":"Номер телефону, пов’язаний із підпискою."},"cid":{"type":"string","description":"Унікальний ідентифікатор користувача."},"eventTypes":{"type":"array","description":"Список типів подій, які буде відстежувати підписка:\n- `ReadyToShip`: Відправлення створено та готове до відправки.\n- `Deleted`: Відправлення видалено.\n- `ParcelPlaceRemoved`: Місце відправлення було видалено з відправлення.\n- `Received`: Відправлення отримано одержувачем.\n- `MoneyTransfer`: Створено грошовий переказ, пов’язаний із відправленням.\n- `MoneyTransferReceived`: Грошовий переказ, пов’язаний із відправленням, виплачено одержувачу.\n- `Returned`: Відправлення повертається або вже повернуто відправнику.\n- `Refused`: Одержувач відмовився прийняти відправлення.\n- `Redirecting`: Відправлення перенаправляється на іншу адресу або у відділення.\n- `Utilization`: Відправлення утилізовано.\n- `Redelivery`: Заплановано повторну спробу доставки відправлення.\n- `UndeliveryReason`: Зафіксовано причину недоставки.\n- `ChangeTime`: Дату або час доставки було змінено.\n- `ArrivalSC`: Відправлення прибуло до сортувального центру.\n- `TransferToPartner`: Відправлення передано партнеру для подальшої доставки.\n- `LoadingCourier`: Відправлення завантажено до транспортного засобу кур’єра.\n- `ArrivalSenderWarehouse`: Відправлення прибуло на склад відправника.\n- `DepartureSenderWarehouse`: Відправлення вибуло зі складу відправника.\n- `InCityRecipient`: Відправлення прибуло до міста одержувача.\n- `AwaitingOnDivision`: Відправлення очікує у відділенні або пункті видачі.\n\n🔸Це поле приймає **лише** типи подій, наведені вище.\nБудь-які значення поза цим списком не підтримуються та не повинні передаватися.\n","items":{"type":"string"}},"sendWarnings":{"type":"boolean","description":"Визначає, чи надсилаються попередження електронною поштою у разі некоректної роботи методу."},"warningEmail":{"type":"string","format":"email","description":"Адреса електронної пошти, яка використовується для надсилання попереджень."},"contentType":{"type":"string","description":"Визначає Content-Type, який використовується для тіла webhook-запитів. Значення за замовчуванням — `application/json`."},"companyTins":{"type":"array","description":"Список податкових ідентифікаційних номерів юридичної особи, пов’язаної з підпискою.","items":{"type":"string"}},"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_active | isActive |
event_types | eventTypes |
send_warnings | sendWarnings |
warning_email | warningEmail |
company_tins | companyTins |
secret_token | secretToken |
secret_token_header_name | secretTokenHeaderName |
created_at | createdAt |
updated_at | updatedAt |
Ці ж застарілі параметри присутні у відповідях на створення та оновлення підписки. Далі в статті вони не повторюються.
---
# 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/new-subscription.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.