> 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/event-types-and-tracking-status-codes.md).

# Типи подій та коди статусів

У роботі з webhook використовуються два різні набори значень, і плутати їх не можна:

* **Типи подій** — це значення, які ви передаєте в параметрі `eventTypes` під час створення або оновлення підписки. Вони визначають, які зміни статусу породжуватимуть webhook-сповіщення.
* **Коди статусів відстеження** — це числові значення, які надходять у тілі webhook-запиту в параметрі `history_tracking[].code`. Саме на них будується бізнес-логіка на вашому боці. Допустимі значення — див. розділ [**Коди статусів відстеження**](#kodi-statusiv-vidstezhennya).

#### Типи подій для параметра eventTypes

```
{
  "eventTypes": ["AwaitingOnDivision", "Received"]
}
```

* Порожній список або відсутній параметр означає, що надходитимуть **усі** підтримувані події.
* Значення чутливі до регістру. Назва з помилкою не спрацює як фільтр, і повідомлення про помилку при створенні підписки ви не отримаєте.

<table data-search="false"><thead><tr><th width="245">Тип події</th><th>Опис</th></tr></thead><tbody><tr><td><code>ReadyToShip</code></td><td>Відправлення створено та готове до відправки.</td></tr><tr><td><code>Deleted</code></td><td>Відправлення видалено.</td></tr><tr><td><code>ParcelPlaceRemoved</code></td><td>Місце відправлення було видалено з відправлення.</td></tr><tr><td><code>Received</code></td><td>Відправлення отримано одержувачем.</td></tr><tr><td><code>MoneyTransfer</code></td><td>Створено грошовий переказ, пов’язаний із відправленням.</td></tr><tr><td><code>MoneyTransferReceived</code></td><td>Грошовий переказ, пов’язаний із відправленням, виплачено одержувачу.</td></tr><tr><td><code>Returned</code></td><td>Відправлення повертається або вже повернуто відправнику.</td></tr><tr><td><code>Refused</code></td><td>Одержувач відмовився прийняти відправлення.</td></tr><tr><td><code>Redirecting</code></td><td>Відправлення перенаправляється на іншу адресу або у відділення.</td></tr><tr><td><code>Utilization</code></td><td>Відправлення утилізовано.</td></tr><tr><td><code>Redelivery</code></td><td>Заплановано повторну спробу доставки відправлення.</td></tr><tr><td><code>UndeliveryReason</code></td><td>Зафіксовано причину недоставки.</td></tr><tr><td><code>ChangeTime</code></td><td>Дату або час доставки було змінено.</td></tr><tr><td><code>ArrivalSC</code></td><td>Відправлення прибуло до сортувального центру.</td></tr><tr><td><code>TransferToPartner</code></td><td>Відправлення передано партнеру для подальшої доставки.</td></tr><tr><td><code>LoadingCourier</code></td><td>Відправлення завантажено до транспортного засобу кур’єра.</td></tr><tr><td><code>ArrivalSenderWarehouse</code></td><td>Відправлення прибуло на склад відправника.</td></tr><tr><td><code>DepartureSenderWarehouse</code></td><td>Відправлення вибуло зі складу відправника.</td></tr><tr><td><code>InCityRecipient</code></td><td>Відправлення прибуло до міста отримувача.</td></tr><tr><td><code>AwaitingOnDivision</code></td><td>Відправлення очікує у відділенні або пункті видачі.</td></tr></tbody></table>

#### Коди статусів відстеження

**Будуйте бізнес-логіку на параметрі** `code`, **а не на** `code_name`. Числовий код є сталим, а назва статусу може змінюватися — вона потрібна лише для того, щоб людині було одразу зрозуміло, про що йдеться. Різні коди можуть мати однакову назву.

Нижче наведено коди статусів, за якими надсилаються webhook-сповіщення.

<table data-search="false"><thead><tr><th width="85" align="center">Код</th><th>Назва статусу відстеження</th></tr></thead><tbody><tr><td align="center"><code>1</code></td><td>Ready to send</td></tr><tr><td align="center"><code>2</code></td><td>Deleted</td></tr><tr><td align="center"><code>4</code></td><td>Accepted for sending</td></tr><tr><td align="center"><code>5</code></td><td>Sent from the Sender's Division</td></tr><tr><td align="center"><code>6</code></td><td>Arrived in the city of the Recipient</td></tr><tr><td align="center"><code>7</code></td><td>Arrived (at the Division)</td></tr><tr><td align="center"><code>8</code></td><td>Arrived (at the Postomat)</td></tr><tr><td align="center"><code>9</code></td><td>Closed</td></tr><tr><td align="center"><code>10</code></td><td>The shipment is closed and the money transfer is sent to the Sender</td></tr><tr><td align="center"><code>11</code></td><td>The shipment is closed and the sender has received the money transfer</td></tr><tr><td align="center"><code>13</code></td><td>Arrival at the transit sorting center</td></tr><tr><td align="center"><code>16</code></td><td>Departure from the transit sorting center</td></tr><tr><td align="center"><code>17</code></td><td>ArrivalTransitWarehouse (currently not used)</td></tr><tr><td align="center"><code>19</code></td><td>DepartureFromTransitWarehouse (currently not used)</td></tr><tr><td align="center"><code>30</code></td><td>Arrived at customs terminal</td></tr><tr><td align="center"><code>31</code></td><td>Departed from customs terminal</td></tr><tr><td align="center"><code>70</code></td><td>Added to manifest</td></tr><tr><td align="center"><code>99</code></td><td>Delivery to Postomat is impossible (technical issues or oversized parcel)</td></tr><tr><td align="center"><code>101</code></td><td>Uploaded to the courier for delivery to the address</td></tr><tr><td align="center"><code>102</code></td><td>Returns (sender ordered a return)</td></tr><tr><td align="center"><code>103</code></td><td>Refusal of shipment</td></tr><tr><td align="center"><code>104</code></td><td>Redirecting</td></tr><tr><td align="center"><code>105</code></td><td>Utilization</td></tr><tr><td align="center"><code>106</code></td><td>Received and created return shipment of Documents/Document Subtypes</td></tr><tr><td align="center"><code>107</code></td><td>At pickup point</td></tr><tr><td align="center"><code>110</code></td><td>Shipment transferred to temporary storage</td></tr><tr><td align="center"><code>111</code></td><td>Failed delivery attempt (in case of targeted delivery)</td></tr><tr><td align="center"><code>112</code></td><td>Delivery date postponed (for targeted delivery)</td></tr><tr><td align="center"><code>113</code></td><td>Storage period expired (Postomat)</td></tr><tr><td align="center"><code>114</code></td><td>Awaiting customs clearance</td></tr><tr><td align="center"><code>115</code></td><td>Arrived at customs terminal</td></tr><tr><td align="center"><code>116</code></td><td>Broker refusal — under resolution</td></tr><tr><td align="center"><code>117</code></td><td>Cargo not found or lost (customs)</td></tr><tr><td align="center"><code>118</code></td><td>Forbidden content — delivery impossible (customs)</td></tr><tr><td align="center"><code>119</code></td><td>Customs clearance in progress</td></tr><tr><td align="center"><code>120</code></td><td>Customs clearance completed</td></tr><tr><td align="center"><code>121</code></td><td>Sent to destination city after customs</td></tr><tr><td align="center"><code>122</code></td><td>Preparing for transfer to customs</td></tr><tr><td align="center"><code>123</code></td><td>Awaiting information from the recipient</td></tr><tr><td align="center"><code>125</code></td><td>Preparing for transfer to customs</td></tr><tr><td align="center"><code>126</code></td><td>Preparing for transfer to customs</td></tr><tr><td align="center"><code>127</code></td><td>Customs declaration data verification in progress</td></tr><tr><td align="center"><code>128</code></td><td>Processing accompanying documents prior to customs</td></tr><tr><td align="center"><code>130</code></td><td>Import prohibited by customs</td></tr><tr><td align="center"><code>131</code></td><td>Return of uncleared cargo</td></tr><tr><td align="center"><code>132</code></td><td>Preparing for return</td></tr><tr><td align="center"><code>133</code></td><td>Client communication regarding a customs comment</td></tr><tr><td align="center"><code>134</code></td><td>The international shipment has been handed over to the customs broker for processing</td></tr><tr><td align="center"><code>135</code></td><td>The international shipment has been placed in Storage Area</td></tr><tr><td align="center"><code>138</code></td><td>Shipment delay due to incorrect recipient information</td></tr><tr><td align="center"><code>141</code></td><td>Storage period expired</td></tr><tr><td align="center"><code>144</code></td><td>Storage period expired</td></tr><tr><td align="center"><code>149</code></td><td>In storage</td></tr><tr><td align="center"><code>155</code></td><td>Shipment transferred for disposal</td></tr><tr><td align="center"><code>197</code></td><td>Processing customs documents</td></tr><tr><td align="center"><code>198</code></td><td>Cargo inspection by customs</td></tr><tr><td align="center"><code>199</code></td><td>Shipment requires customs clearance</td></tr><tr><td align="center"><code>999</code></td><td>Undetermined</td></tr></tbody></table>

#### Мінімальний алгоритм обробника

1. Перевірити секретний заголовок.
2. Розібрати тіло запиту.
3. Взяти UUID повідомлення із заголовка x-np-attempt — частину до крапки.
4. Якщо цей UUID уже оброблено — повернути 2xx і завершити обробку.
5. Зберегти дані та UUID однією транзакцією.
6. Повернути 2xx.
7. Виконати бізнес-обробку окремо, поза межами цього запиту.

### Особливості, які варто врахувати

<table data-search="false"><thead><tr><th width="257">Situation</th><th>Що робити</th></tr></thead><tbody><tr><td>Бізнес-логіка на назві статусу ненадійна.</td><td>Використовуйте <code>code</code>. Він сталий, тоді як <code>code_name</code> може змінитися, а різні коди можуть мати однакову назву.</td></tr><tr><td>Оновлення підписки скидає параметри, які не були передані в запиті.</td><td>Під час виклику <code>PUT</code> завжди передавайте повний набір параметрів, навіть якщо змінюєте один. Перед оновленням отримайте поточні налаштування методом <a href="/methods/ua/overview/webhooks/subscription-list.md"><strong>Отримати всі підписки</strong></a>.</td></tr><tr><td>Тип підписки змінити не можна.</td><td>Щоб перейти на інший тип, створіть нову підписку й видаліть стару.</td></tr><tr><td>Видалення номерів повертає код <code>200</code> навіть тоді, коли не видалено жодного номера.</td><td>Перевіряйте параметр status у тілі відповіді, а не HTTP-код.</td></tr><tr><td>Додавання номерів може спрацювати частково.</td><td>Завжди звіряйте <code>missedNumbers</code>. Номери, яких ще немає в системі, потрібно додати повторно пізніше.</td></tr><tr><td>Кожне webhook-сповіщення містить усю історію, а не лише нову подію.</td><td>Зберігайте у себе останній оброблений стан і порівнюйте з ним.</td></tr><tr><td>Одне сповіщення може надійти кілька разів.</td><td>Обробник має бути стійким до повторів — використовуйте UUID із заголовка <code>x-np-attempt</code>.</td></tr><tr><td>Події за час вимкненої підписки не зберігаються.</td><td>Після повторного ввімкнення підписки пропущені події не надійдуть. Якщо потрібна повна історія за цей період, отримайте її через методи трекінгу.</td></tr><tr><td>Кілька підписок на ті самі відправлення не дають більше сповіщень.</td><td>Webhook-сповіщення надсилається один раз незалежно від кількості підписок, під які підпадає відправлення. Дублювати підписки не потрібно.</td></tr><tr><td>Номери не відв’язуються від підписки автоматично.</td><td>Навіть після доставки відправлення його номер залишається в підписці. Видаляйте номери самостійно, коли вони більше не потрібні.</td></tr><tr><td><code>text/plain</code> як значення <code>contentType</code> буде виведено з підтримки.</td><td>Переходьте на <code>application/json</code>. Тіло запиту при цьому не зміниться.</td></tr><tr><td>У Sandbox webhook-сповіщення за реальними змінами статусів не надсилаються.</td><td>Перевіряйте інтеграцію методом <a href="/methods/ua/overview/webhooks/test-webhook.md"><strong>Перевірка тестового webhook</strong></a>. Відсутність webhook-сповіщень у Sandbox не означає помилки в налаштуванні.</td></tr></tbody></table>

<br>

<br>


---

# 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/event-types-and-tracking-status-codes.md?ask=<question>&goal=<endgoal>
```

`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.