Skip to Content
FastracDocs

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

EventFires whendata.status after the event
shipment.dispatchedThe courier accepted the booking and issued an airway billPENDING_PICKUP or PENDING_DROPOFF (flat payload)
shipment.pending_pickupThe courier is waiting to pick up, or a driver was assignedPENDING_PICKUP (unchanged for driver updates)
shipment.in_transitThe parcel was picked up or moved along the routeIN_TRANSIT
shipment.deliveredThe parcel was deliveredDELIVERED
shipment.cancelledThe shipment was cancelled, by you or by the courierCANCELLED
shipment.problem_detectedThe courier reported a problem, for example a lost or damaged parcelPROBLEM_SHIPMENT
shipment.pickup_failedAn instant courier could not complete the pickup, for example no driver accepted itPROBLEM_SHIPMENT
shipment.rts_confirmedThe courier started returning the parcel to the senderRTS_CONFIRMED
shipment.rts_transitThe returning parcel is moving backRTS_TRANSIT
shipment.rts_problem_shipmentThe courier reported a problem during the returnRTS_PROBLEM_SHIPMENT
shipment.rts_deliveredThe parcel was returned to the senderRTS_DELIVERED
shipment.airway_bill_updatedThe courier replaced the airway bill, for example for a return or rerouteUnchanged
shipment.price_changedThe courier changed the price, usually after reweighingUnchanged
shipment.measurement_changedThe courier remeasured the weight or sizeUnchanged
shipment.rts_billedA return (RTS) fee was chargedUnchanged
shipment.status_updatedAny other status changeThe 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:

DeliveredBody
{
  "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
  }
}
FieldTypeDescription
booking_idstringThe order code (FSO-…) the shipment belongs to.
awbstring or nullThe courier's airway bill (resi).
courier_codestringThe courier, in lower case: jne, jnt, spx, lalamove, …
shipment_codestringThe shipment code (SHP-…). Use it to match your records and to call the shipments API.
data.timestampstringWhen the change happened, as YYYY-MM-DD HH:mm:ss in UTC, without an offset. Parse it as UTC.
data.statusstringThe shipment's status after this event. See Shipment statuses.
data.descstringA human-readable description, often the courier's own text. It may be in Indonesian. Show it, but don't parse it.
data.notestring or nullExtra note from the courier, if any.
data.mapping_codestring or nullThe 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_platestring or nullThe driver, when the courier assigned one (mainly instant couriers).
data.proof_imagestring or nullURL of the proof-of-delivery photo, when the courier provides one.
data.receiver_name, data.receiver_relationstring or nullWho received the parcel, when the courier reports it.
data.tracking_linkstring or nullA 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:

DeliveredBody
{
  "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"
}
FieldDescription
shipment_id, order_idNumeric internal IDs. Use shipment_code instead.
shipment_codeThe shipment code (SHP-…).
statusPENDING_PICKUP or PENDING_DROPOFF, depending on the fulfilment method.
tracking_idThe courier's booking reference. Often the same as the airway bill.
tracking_urlCourier tracking page, or null.
airway_billThe 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.

DeliveredBody (driver assigned)
{
  "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.

DeliveredBody
{
  "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:

DeliveredBody
{
  "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.

DeliveredBody
{
  "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"
  }
}
FieldDescription
price_before, price_afterShipment total before and after the change, in IDR.
deltaprice_after − price_before, in IDR.
payment_statussuccess: 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:

DeliveredBody
{
  "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).

DeliveredBody
{
  "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"
  }
}
FieldDescription
rts_feeThe return fee, in IDR.
payment_statussuccess: 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.

Was this page helpful?

On this page