API ReferenceShipments
Webhook
Receive shipment status updates from Nhất Tín through the partner callback URL.
POST
Partner callback URLNhất Tín sends a webhook payload whenever a shipment status changes.
Auth: Callback URL configured by partner
Configure the webhook on the Web portal
Header key: Authorization
Header token value: from Partner
Request body
| Field | Type | Required | Description |
|---|---|---|---|
bill_no | string | Yes | Nhất Tín shipment code. |
ref_code | string | Yes | Customer reference code. |
status_id | number | Yes | Status ID. |
status_name | string | Yes | Status name. |
status_time | number | Yes | Time when the status changed. |
push_time | number | Yes | Time when Nhất Tín pushed the webhook. |
shipping_fee | number | Yes | Shipping fee. |
is_partial | number | Yes | 1 when the shipment is returned from partial delivery. |
reason | string | No | Reason, if available. |
weight | number | Yes | Cargo weight. |
dimension_weight | number | Yes | Dimensional weight. |
length | number | Yes | Length in cm. |
width | number | Yes | Width in cm. |
height | number | Yes | Height in cm. |
expected_at | string | Yes | Expected delivery date in YYYY-MM-DD HH:mm:ss format. |
{
"bill_no": "CP16658276R",
"ref_code": "40724974",
"status_id": 3,
"status_name": "Da lay hang",
"status_time": 1681382601,
"push_time": 1681382738,
"shipping_fee": 38610,
"is_partial": 1,
"weight": 2,
"dimension_weight": 1,
"length": 1,
"width": 1,
"height": 1,
"expected_at": "2024-08-02 09:00:00"
}Recommended handling
- Return HTTP
2xxafter your system receives the webhook successfully. - Dedupe by the
bill_no,status_id, andstatus_timetuple to avoid duplicate processing. - Log
push_timeand the original payload for operational reconciliation.