Events
Every webhook event Shipping Engine sends, when it fires, and what its payload contains.
- Product
- APIShipping Engine API
- Section
- Webhooks
- Reading time
- 9 min read
Every event is about one shipment. The event name is in the x-webhook-event-type header; the body
is the payload, with no envelope around it.
Summary
| Event | Fires when | data.status after the event |
|---|---|---|
shipment.dispatched | The courier accepted the booking and issued an airway bill | PENDING_PICKUP or PENDING_DROPOFF (flat payload) |
shipment.pending_pickup | The courier is waiting to pick up, or a driver was assigned | PENDING_PICKUP (unchanged for driver updates) |
shipment.in_transit | The parcel was picked up or moved along the route | IN_TRANSIT |
shipment.delivered | The parcel was delivered | DELIVERED |
shipment.cancelled | The shipment was cancelled, by you or by the courier | CANCELLED |
shipment.problem_detected | The courier reported a problem, for example a lost or damaged parcel | PROBLEM_SHIPMENT |
shipment.pickup_failed | An instant courier could not complete the pickup, for example no driver accepted it | PROBLEM_SHIPMENT |
shipment.rts_confirmed | The courier started returning the parcel to the sender | RTS_CONFIRMED |
shipment.rts_transit | The returning parcel is moving back | RTS_TRANSIT |
shipment.rts_problem_shipment | The courier reported a problem during the return | RTS_PROBLEM_SHIPMENT |
shipment.rts_delivered | The parcel was returned to the sender | RTS_DELIVERED |
shipment.airway_bill_updated | The courier replaced the airway bill, for example for a return or reroute | Unchanged |
shipment.price_changed | The courier changed the price, usually after reweighing | Unchanged |
shipment.measurement_changed | The courier remeasured the weight or size | Unchanged |
shipment.rts_billed | A return (RTS) fee was charged | Unchanged |
shipment.status_updated | Any other status change | The new status |
For what each status means and which changes are possible, see Shipment statuses and Order lifecycle.
Payload
All events except shipment.dispatched share this shape:
{
"booking_id": "FSO-261120-K3M9QZ",
"awb": "JX3920018472",
"courier_code": "jnt",
"shipment_code": "SHP-261120-7RT2WX",
"data": {
"timestamp": "2026-11-20 06:41:07",
"status": "IN_TRANSIT",
"desc": "Paket telah sampai di gateway Jakarta",
"note": null,
"mapping_code": "TRANSIT",
"driver_name": null,
"driver_phone": null,
"driver_license_plate": null,
"proof_image": null,
"receiver_name": null,
"receiver_relation": null,
"tracking_link": null
}
}| Field | Type | Description |
|---|---|---|
booking_id | string | The order code (FSO-…) the shipment belongs to. |
awb | string or null | The courier's airway bill (resi). |
courier_code | string | The courier, in lower case: jne, jnt, spx, lalamove, … |
shipment_code | string | The shipment code (SHP-…). Use it to match your records and to call the shipments API. |
data.timestamp | string | When the change happened, as YYYY-MM-DD HH:mm:ss in UTC, without an offset. Parse it as UTC. |
data.status | string | The shipment's status after this event. See Shipment statuses. |
data.desc | string | A human-readable description, often the courier's own text. It may be in Indonesian. Show it, but don't parse it. |
data.note | string or null | Extra note from the courier, if any. |
data.mapping_code | string or null | The courier's raw status code. Useful for support; don't build logic on it, because each courier uses its own codes. |
data.driver_name, data.driver_phone, data.driver_license_plate | string or null | The driver, when the courier assigned one (mainly instant couriers). |
data.proof_image | string or null | URL of the proof-of-delivery photo, when the courier provides one. |
data.receiver_name, data.receiver_relation | string or null | Who received the parcel, when the courier reports it. |
data.tracking_link | string or null | A live tracking link from the courier, when available. |
Expect new fields
Shipping Engine may add fields to payloads. Ignore fields you don't know instead of rejecting the
event. The x-webhook-schema-version header (2025-10-01) changes only for breaking changes.
Billing events (price_changed, measurement_changed, rts_billed) and some
airway_bill_updated events carry a shorter data object: timestamp, status, desc and the
event's own fields. Driver and receiver fields are not included.
Status events
shipment.dispatched
Fires once per shipment, right after the courier accepts the booking. For most couriers this happens
while POST /b2b/orders is running, so the event can arrive before or just after your API response.
Use it to save the airway bill and tracking link.
This event has its own flat payload:
{
"shipment_id": 81234,
"shipment_code": "SHP-261120-7RT2WX",
"order_id": 55671,
"status": "PENDING_DROPOFF",
"tracking_id": "JX3920018472",
"tracking_url": "https://tracking.example/jnt/JX3920018472",
"airway_bill": "JX3920018472"
}| Field | Description |
|---|---|
shipment_id, order_id | Numeric internal IDs. Use shipment_code instead. |
shipment_code | The shipment code (SHP-…). |
status | PENDING_PICKUP or PENDING_DROPOFF, depending on the fulfilment method. |
tracking_id | The courier's booking reference. Often the same as the airway bill. |
tracking_url | Courier tracking page, or null. |
airway_bill | The airway bill (resi), or null if the courier issues it later. |
There is no booking_id or data object. Look up the order with shipment_code if you need it.
shipment.pending_pickup
Fires when the courier reports the parcel is waiting to be picked up, and also when a driver is
assigned or changes, which is common with instant couriers (Lalamove, GrabExpress, Paxel, Dash). In
that case the driver fields are filled and the status usually stays PENDING_PICKUP.
{
"booking_id": "FSO-261120-P8L2DA",
"awb": "LLM-2611200932",
"courier_code": "lalamove",
"shipment_code": "SHP-261120-Q4NB7C",
"data": {
"timestamp": "2026-11-20 02:05:31",
"status": "PENDING_PICKUP",
"desc": "Driver sedang menuju lokasi penjemputan",
"note": null,
"mapping_code": "ON_GOING",
"driver_name": "Budi Santoso",
"driver_phone": "081234567890",
"driver_license_plate": "B 1234 XYZ",
"proof_image": null,
"receiver_name": null,
"receiver_relation": null,
"tracking_link": "https://share.lalamove.example/abc123"
}
}You can receive several pending_pickup events for one shipment. Always show the latest driver.
A failed pickup attempt that the courier will retry also keeps the shipment in PENDING_PICKUP.
shipment.in_transit
Fires when the courier picks up the parcel, and again as it moves through hubs. Each event has a new
desc. Use the latest one for your tracking timeline. Payload: see Payload.
shipment.delivered
Fires when the courier confirms delivery. DELIVERED is final: no later event changes it.
proof_image, receiver_name and receiver_relation are filled when the courier provides them.
{
"booking_id": "FSO-261120-K3M9QZ",
"awb": "JX3920018472",
"courier_code": "jnt",
"shipment_code": "SHP-261120-7RT2WX",
"data": {
"timestamp": "2026-11-21 08:12:44",
"status": "DELIVERED",
"desc": "Paket telah diterima",
"note": null,
"mapping_code": "DELIVERED",
"driver_name": null,
"driver_phone": null,
"driver_license_plate": null,
"proof_image": "https://cdn.example/pod/JX3920018472.jpg",
"receiver_name": "Siti",
"receiver_relation": "Keluarga",
"tracking_link": null
}
}For COD shipments, the collected cash reaches your balance after delivery. See Balance and charges.
shipment.cancelled
Fires when the shipment is cancelled: by you (API or dashboard), by the courier, or because the
courier rejected the booking. desc contains the reason when one is known. A paid shipment is
refunded to your balance. See Cancellations and refunds.
shipment.problem_detected
Fires when the courier reports a problem it can't solve on its own, for example a lost or damaged
parcel, or a delivery that can't continue. Status becomes PROBLEM_SHIPMENT. Read desc, and
contact support if you need help. The shipment can still move on to another status later.
shipment.pickup_failed
Fires when an instant courier booking could not be picked up, for example no driver accepted it or
the courier rejected it. Status becomes PROBLEM_SHIPMENT. Consider cancelling and booking again,
possibly with another courier.
Return (RTS) events
A return to sender (RTS) happens when the courier can't deliver and brings the parcel back. Once a
shipment is in an RTS_* status, it never goes back to a normal delivery status. See
Returns (RTS).
shipment.rts_confirmed
The courier confirmed the parcel will be returned. Status: RTS_CONFIRMED.
shipment.rts_transit
The returning parcel is on its way back. Status: RTS_TRANSIT. Can fire several times.
shipment.rts_problem_shipment
The courier reported a problem during the return. Status: RTS_PROBLEM_SHIPMENT.
shipment.rts_delivered
The parcel is back with the sender. Status: RTS_DELIVERED, which is final. For a COD shipment, no
cash was collected, so there is no COD payout.
Change events
These events report a change to an existing shipment. data.status is the shipment's current
status, unchanged by the event.
shipment.airway_bill_updated
The courier issued a new airway bill, for example for a return or a reroute. The top-level awb is
the new airway bill. Update your records and tracking links. When the courier reports both
numbers, data contains awb_before and awb_after:
{
"booking_id": "FSO-261120-K3M9QZ",
"awb": "11002233445566",
"courier_code": "lion",
"shipment_code": "SHP-261120-7RT2WX",
"data": {
"status": "RTS_TRANSIT",
"desc": "Airway bill updated due to return / reroute",
"awb_before": "11009988776655",
"awb_after": "11002233445566",
"timestamp": "2026-11-22 04:30:00"
}
}Otherwise data has the standard fields from Payload.
shipment.price_changed
The courier changed the shipping price, usually after reweighing the parcel. Amounts are IDR integers.
{
"booking_id": "FSO-261120-K3M9QZ",
"awb": "SPXID0123456789",
"courier_code": "spx",
"shipment_code": "SHP-261120-7RT2WX",
"data": {
"status": "IN_TRANSIT",
"desc": "Shipment price adjusted due to courier reweigh",
"price_before": 18500,
"price_after": 27500,
"delta": 9000,
"payment_status": "success",
"timestamp": "2026-11-20 10:02:19"
}
}| Field | Description |
|---|---|
price_before, price_after | Shipment total before and after the change, in IDR. |
delta | price_after − price_before, in IDR. |
payment_status | success: the difference was deducted from your balance. failed: your balance was too low; Fastrac support will follow up. not_required: nothing to charge, for example on a COD shipment. |
See Adjustments for which changes are charged.
shipment.measurement_changed
The courier remeasured the parcel. The values are text, for display:
{
"booking_id": "FSO-261120-K3M9QZ",
"awb": "NV-ID-77120043",
"courier_code": "ninja",
"shipment_code": "SHP-261120-7RT2WX",
"data": {
"status": "IN_TRANSIT",
"desc": "Measurement adjusted by courier",
"measurement_before": "weight=1000g, dimension=10x10x10cm",
"measurement_after": "weight=2000g, dimension=20x20x20cm",
"timestamp": "2026-11-20 10:02:19"
}
}A price change caused by the new measurement arrives as a separate shipment.price_changed event.
shipment.rts_billed
A return fee was charged for the shipment. Some couriers charge the full original shipping fee for a return; others charge nothing. See Returns (RTS).
{
"booking_id": "FSO-261120-K3M9QZ",
"awb": "JX3920018472",
"courier_code": "jnt",
"shipment_code": "SHP-261120-7RT2WX",
"data": {
"status": "RTS_TRANSIT",
"desc": "RTS Billed",
"rts_fee": 18500,
"payment_status": "success",
"timestamp": "2026-11-23 01:15:00"
}
}| Field | Description |
|---|---|
rts_fee | The return fee, in IDR. |
payment_status | success: deducted from your balance. failed: your balance was too low; Fastrac support will follow up. |
shipment.status_updated
Fires for any status change that has no event of its own, for example a shipment moving to
PENDING_DROPOFF. It uses the standard Payload. Read data.status to see the new status.
Subscribe with shipment.* so you receive it.
Related
- Verify signatures: check every event before you trust it.
- Delivery and retries: ordering, duplicates and reconciliation.
- API reference: the webhook endpoints and the shipments API.
Was this page helpful?