Webhooks 1

Webhook — це спосіб отримувати зміни статусів відправлень без періодичних запитів із вашого боку. Ви один раз вказуєте URL зворотного виклику, і Nova Post самостійно надсилає на нього webhook-сповіщення щоразу, коли статус відправлення змінюється.

Налаштування такого зв’язку називається підпискою. Ця стаття описує, як створити підписку, керувати нею та що саме надходить на ваш сервер.

Як це працює

1. Ви створюєте підписку й вказуєте URL зворотного виклику та тип відправлень, які вас цікавлять.
2. Nova Post відстежує зміни статусів відправлень, що підпадають під цю підписку.
3. Щойно статус змінюється, на ваш URL надходить POST-запит із номером відправлення та історією його статусів.
4. Ваш сервер відповідає кодом 2xx — це підтверджує, що сповіщення отримано.

Коли надсилається webhook-сповіщення

Webhook-сповіщення надсилається тоді, коли статус відправлення змінюється на новий.

Сповіщення про події, які відбулися до створення підписки, надсилатися не будуть. Сповіщення надсилаються лише за час існування активної підписки.

В історії відстеження один і той самий код статусу може повторюватися кілька разів поспіль. У такому разі webhook-сповіщення надсилається лише один раз — коли цей статус встановлено вперше. Наступне сповіщення надійде тоді, коли статус зміниться на інший.

Порівняння виконується з попереднім статусом, а не з усією історією. Тому якщо статус повернувся до попереднього значення після іншого, це вважається новою зміною і webhook-сповіщення надійде знову.

Послідовність статусів	Кількість webhook-сповіщень	На які статуси
4 → 4 → 4 → 5	2	4, 5
4 → 5 → 5 → 9	3	4, 5, 9
4 → 5 → 4	3	4, 5, знову 4

Якщо відправлення підпадає одразу під кілька ваших підписок, webhook-сповіщення надсилається один раз — система захищає від дублювання. Створювати кілька підписок на ті самі відправлення не потрібно.

Відповідь вашого сервера

Ваш сервер має відповісти кодом із діапазону 2xx — це означає, що сповіщення прийнято. Будь-яка інша відповідь, як і відсутність відповіді, вважається невдалою доставкою.

Не виконуйте тривалу обробку до того, як відповісте: прийміть сповіщення, збережіть його у власну чергу й одразу поверніть 2xx, а бізнес-обробку виконуйте окремо.

Повторні спроби

Якщо ваш сервер недоступний, не встиг відповісти або повернув код помилки, система виконує до 6 повторних спроб доставки зі зростаючими інтервалами:

Спроба	Інтервал після попередньої
1-ша повторна	5 секунд
2-га повторна	10 секунд
3-тя повторна	20 секунд
4-та повторна	40 секунд
5-та повторна	80 секунд
6-та повторна	160 секунд

Якщо в підписці ввімкнено sendWarnings, після третьої невдалої спроби доставки одного повідомлення на адресу з warningEmail надходить лист про проблему.

Після шостої невдалої спроби повторне надсилання цього повідомлення припиняється. Сама підписка при цьому не змінюється й залишається активною: коли статус відправлення зміниться наступного разу, буде сформовано нове webhook-сповіщення, і його доставка почнеться заново.

Захист від повторної обробки

Через повторні спроби ваш сервер може отримати одне й те саме сповіщення кілька разів. Щоб це не спричинило подвійної обробки, використовуйте заголовок x-np-attempt.

Заголовок має формат {UUID повідомлення}.{номер спроби}:

x-np-attempt: 8f14e45f-ceea-467e-9a3a-0e1a1b1e2b1c.1
x-np-attempt: 8f14e45f-ceea-467e-9a3a-0e1a1b1e2b1c.2

Обидва рядки — це одне й те саме сповіщення, надіслане двічі. UUID до крапки незмінний для всіх спроб доставки однієї події та унікальний для різних подій, тому саме він є ключем перевірки на повтор. Номер після крапки показує, яка це за рахунком спроба.

Перед початком

Що підготувати

#	Що потрібно	Пояснення
1	Публічний HTTPS-endpoint	Адреса на вашому сервері, яка приймає POST-запити. Має бути доступною з інтернету й не виконувати переадресацій.
2	JWT-токен	Потрібен для авторизації запитів до API Nova Post.
3	Власний секретний токен	Рядок, який ви формуєте самі. Nova Post додаватиме його до кожного webhook-запиту, щоб ваш сервер міг переконатися, що запит надійшов саме від Nova Post.
4	Перелік відправлень або правило їх відбору	Залежить від типу підписки — див. розділ «Типи підписок».
5	Перелік типів подій	Необов’язково. Якщо фільтр не потрібен, надходитимуть усі підтримувані події. Допустимі значення — див. розділ «Типи подій для параметра eventTypes».

JWT-токен і власний секретний токен — це різні облікові дані з різним призначенням. JWT-токен потрібен, щоб Nova Post авторизувала ваші запити. Секретний токен потрібен, щоб ви могли перевіряти вхідні webhook-запити. Не використовуйте один замість іншого й не передавайте JWT-токен в URL зворотного виклику.

Середовища

Середовище	Базовий URL	Призначення
Sandbox	https://api-stage.novapost.com/v.1.0/	Перевірка інтеграції. У Sandbox працює виключно тестова відправка webhook — реальні зміни статусів відправлень webhook-сповіщень не породжують.
PROD	https://api.novapost.com/v.1.0/	Робоче середовище.

Структура webhook-запиту

Заголовки

Заголовок	Опис
Content-Type	Content-Type, заданий у параметрі contentType підписки. За замовчуванням text/plain.
X-NP-Key або власна назва	Секретний токен підписки. Назва заголовка береться з параметра secretTokenHeaderName; якщо його не задано, використовується X-NP-Key.
x-np-attempt	Ідентифікатор спроби доставки у форматі {UUID повідомлення}.{номер спроби}. Використовується для захисту від повторної обробки.

Тіло запиту

{
  "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"
    }
  ]
}

Параметр	Тип	Опис
number	string	Номер відправлення.
scheduled_delivery_date	string	Запланована дата й час доставки у форматі ISO 8601. Може бути порожнім.
history_tracking	string[]	Масив об’єктів статусів відстеження.
history_tracking[].code	string	Код статусу відстеження. Будуйте бізнес-логіку саме на цьому параметрі — він сталий. Допустимі значення — див. розділ «Коди статусів відстеження».
history_tracking[].code_name	string	Назва статусу відстеження. Може змінюватися й потрібна лише для зручності читання — не використовуйте її для порівнянь у коді.
history_tracking[].country_code	string	Код країни, у якій було зафіксовано статус. Може бути порожнім.
history_tracking[].settlement	string	Назва населеного пункту. Може бути порожнім.
history_tracking[].date	string	Дата й час події статусу.

Тіло webhook-запиту містить щонайменше один статус відстеження. Кожне наступне webhook-сповіщення містить новий доданий статус і всі раніше доставлені статуси. Актуальний статус матиме найновіше значення поля date.

Авторизація

Кожен запит до API має містити заголовок Authorization із JWT-токеном:

Authorization: {jwt}

Термін дії токена — приблизно 1 година, після цього потрібно запросити новий. Порядок отримання токена описано у статті Авторизація.

Список методів

Назва	Опис
Отримати всі підписки	Отримати список усіх підписок, пов’язаних із клієнтом.
Створити нову підписку	Цей метод використовується для створення нової підписки для отримання сповіщень про відстеження через webhook. Підписка може бути різних типів, наприклад для окремого номера або для компанії, і є необхідною для клієнтів, які хочуть отримувати оновлення статусів відправлень у реальному часі.
Оновити існуючу підписку	Цей метод оновлює дані існуючої підписки, зокрема callback URL, статус активності, типи подій тощо. Він використовується для зміни налаштувань підписки клієнтами, які хочуть керувати способом отримання сповіщень про відстеження. Метод виконує повну заміну налаштувань, а не часткове оновлення. Параметри, які ви не передасте, буде скинуто. Наприклад, якщо змінити лише url, підписка втратить фільтр eventTypes і почне отримувати webhook-сповіщення за всіма подіями. Завжди передавайте повний набір параметрів, навіть якщо змінюєте один із них. Тип підписки змінити не можна. Якщо передати в запиті параметр type з іншим значенням, зміна не застосується. Щоб перейти на інший тип, створіть нову підписку й видаліть стару. Зверніть увагу: події, що відбудуться за час, поки підписка вимкнена, після її повторного ввімкнення не надійдуть.
Видалити підписку	Цей метод видаляє підписку, зазначену за її унікальним ідентифікатором. Після видалення підписка більше не отримуватиме webhook-сповіщення. Видалення є незворотним, тому цю дію слід виконувати з обережністю. Якщо потрібно лише тимчасово зупинити надсилання webhook-сповіщень, не видаляйте підписку, а вимкніть її методом «Оновити існуючу підписку» зі значенням isActive: false. Зверніть увагу: події, що відбудуться за час, поки підписка вимкнена, після її повторного ввімкнення не надійдуть.
Додати номери до існуючої підписки	Цей метод дозволяє додавати номери відправлень до підписки типу numbers. Додаються лише ті номери, які вже існують у системі Nova Post. Номер, якого ще немає в системі, до підписки не потрапить — його потрібно буде додати повторно після того, як відправлення буде створено. Код 200 означає, що додано щонайменше один номер, а не обов’язково всі передані. Завжди перевіряйте вміст missedNumbers.
Видалити номери з існуючої підписки	Цей метод дозволяє видаляти номери відправлень із підписки типу numbers. Метод повертає код 200 у будь-якому разі, зокрема й тоді, коли не видалено жодного номера. Результат операції визначається параметром status у тілі відповіді, а не HTTP-кодом.
Перевірка тестового webhook	Цей метод дозволяє перевірити роботу webhook. Для успішної відповіді потрібна щонайменше одна активна підписка.