> 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/event-types-and-tracking-status-codes.md). # Event types and tracking status codes Two different sets of values are used when working with webhooks, and they must not be confused: * **Event types** are the values you pass in the `eventTypes` parameter when creating or updating a subscription. They define which status changes generate webhook notifications. * **Tracking status codes** are the numeric values that arrive in the webhook request body in the `history_tracking[].code` parameter. Your business logic is built on them. For the allowed values, see the [**Tracking status codes**](#tracking-status-codes) section. #### Event types for the eventTypes parameter ``` { "eventTypes": ["AwaitingOnDivision", "Received"] } ``` * An empty list or an absent parameter means that **all** supported events are sent. * The values are case-sensitive. A misspelled name does not work as a filter, and you do not receive an error message when the subscription is created.

Event type	Description
`ReadyToShip`	The shipment has been created and is ready for dispatch.
`Deleted`	The shipment has been deleted.
`ParcelPlaceRemoved`	A parcel has been removed from the shipment.
`Received`	The shipment has been received by the recipient.
`MoneyTransfer`	A money transfer related to the shipment has been created.
`MoneyTransferReceived`	The money transfer related to the shipment has been paid out to the recipient.
`Returned`	The shipment is being returned or has been returned to the sender.
`Refused`	The recipient has refused to accept the shipment.
`Redirecting`	The shipment is being redirected to another address or branch.
`Utilization`	The shipment has been disposed of.
`Redelivery`	A repeat delivery attempt for the shipment has been scheduled.
`UndeliveryReason`	A non-delivery reason has been recorded.
`ChangeTime`	The delivery date or time has been changed.
`ArrivalSC`	The shipment has arrived at the sorting center.
`TransferToPartner`	The shipment has been handed over to a partner for further delivery.
`LoadingCourier`	The shipment has been loaded onto the courier's vehicle.
`ArrivalSenderWarehouse`	The shipment has arrived at the sender's warehouse.
`DepartureSenderWarehouse`	The shipment has departed from the sender's warehouse.
`InCityRecipient`	The shipment has arrived in the recipient's city.
`AwaitingOnDivision`	The shipment is waiting at the branch or pickup point.

#### Tracking status codes **Build your business logic on the** `code` **parameter, not on** `code_name`. The numeric code is stable, while the status name may change — it is provided only so that a person can immediately understand what it refers to. Different codes may have the same name. The tracking status codes for which webhook notifications are sent are listed below.

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

#### Minimum handler algorithm 1. Validate the secret header. 2. Parse the request body. 3. Take the message UUID from the x-np-attempt header — the part before the dot. 4. If this UUID has already been processed — return 2xx and finish processing. 5. Save the data and the UUID in a single transaction. 6. Return 2xx. 7. Perform the business logic separately, outside this request. ### Things to keep in mind

Situation	What to do
Business logic based on the status name is unreliable.	Use `code`. It is stable, while `code_name` may change, and different codes may have the same name.
Updating a subscription resets the parameters that were not passed.	When calling `PUT`, always pass the full set of parameters, even if you change only one. Retrieve the current settings with the Retrieve all subscriptions method before updating.
The subscription type cannot be changed.	To switch to another type, create a new subscription and delete the old one.
Deleting numbers returns a `200` code even when no numbers were deleted.	Check the status parameter in the response body, not the HTTP code.
Adding numbers may work only partially.	Always check `missedNumbers`. Numbers that do not yet exist in the system have to be added again later.
Every webhook notification contains the whole history, not only the new event.	Store the last processed state on your side and compare against it.
The same notification may arrive several times.	The handler must be resilient to repeats — use the UUID from the `x-np-attempt` header.
Events that occur while a subscription is disabled are not stored.	Missed events are not delivered after the subscription is enabled again. If you need the full history for that period, retrieve it via the tracking methods.
Several subscriptions for the same shipments do not produce more notifications.	A webhook notification is sent once, regardless of how many subscriptions cover the shipment. There is no need to duplicate subscriptions.
Numbers are not unlinked from a subscription automatically.	Even after a shipment has been delivered, its number remains in the subscription. Delete the numbers yourself when they are no longer needed.
`text/plain` as the value of `contentType` will be discontinued.	Switch to `application/json`. The request body does not change.
In Sandbox, webhook notifications for real status changes are not sent.	Test the integration with the Checking the test webhook method. The absence of webhook notifications in Sandbox does not mean that the configuration is wrong.

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