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