Shipment

Sample payloads for every shipment webhook event.

Shipment webhooks come in three shapes. Which one you get depends on the event.

Events	Payload
shipment.updated, shipment.in-transit, shipment.delivered, shipment.cancelled, shipment.returned, shipment.awaiting-clearance, shipment.pending-cancellation	A lean tracking snapshot.
shipment.created	A fuller shipment object.
shipment.customs_event	A small customs-delay object.

Status events

These carry a tracking snapshot, not the whole shipment. Addresses and the parcel appear as ids, not embedded objects — call Get Shipment if you need the full record.

All seven status events share this shape; only status, sub_statuses, events and the delivery_* flags differ.

shipment.delivered

{
    "event": "shipment.delivered",
    "data": {
        "shipment_id": "SH-40208776515",
        "user": "USER-27450202164",
        "status": "delivered",
        "sub_statuses": [],
        "rate": "RT-64093387231",
        "carrier": "CA-85479996273",
        "tracking_number": "7412089553",
        "events": [
            {
                "status": "confirmed",
                "description": "Shipment arranged successfully by User.",
                "location": "Lagos, NG",
                "created_at": "2026-09-15T09:02:11.903Z"
            },
            {
                "status": "in-transit",
                "description": "Shipment picked up by carrier.",
                "location": "Lagos, NG",
                "created_at": "2026-09-15T14:38:40.512Z"
            },
            {
                "status": "delivered",
                "description": "Delivered - Signed for by: A. OBI",
                "location": "London, GB",
                "created_at": "2026-09-18T11:20:07.884Z"
            }
        ],
        "extras": {
            "tracking_number": "7412089553",
            "tracking_url": "https://track.terminal.africa/SH-40208776515",
            "carrier_tracking_url": "https://www.dhl.com/ng-en/home/tracking.html?tracking-id=7412089553",
            "shipping_label_url": "https://assets.terminal.africa/labels/SH-40208776515.pdf",
            "proof_of_delivery": {
                "url": "https://assets.terminal.africa/pod/SH-40208776515.pdf",
                "type": "signature",
                "signed_by": "A. OBI",
                "fetched_at": "2026-09-18T11:34:52.006Z"
            }
        },
        "metadata": {
            "order_id": "ORD-10023"
        },
        "address_to": "AD-00632494668",
        "address_from": "AD-00632494667",
        "parcel": "PC-09857312356",
        "pickup_date": "2026-09-15T14:00:00.000Z",
        "delivery_date": "2026-09-18T11:20:07.884Z",
        "delivery_arranged": true,
        "delivery_picked_up": true,
        "delivery_delivered": true,
        "created_at": "2026-09-15T09:02:11.903Z",
        "updated_at": "2026-09-18T11:20:07.884Z"
    }
}

shipment.in-transit

Fires once, the first time a shipment moves.

{
    "event": "shipment.in-transit",
    "data": {
        "shipment_id": "SH-40208776515",
        "user": "USER-27450202164",
        "status": "in-transit",
        "sub_statuses": [],
        "rate": "RT-64093387231",
        "carrier": "CA-85479996273",
        "tracking_number": "7412089553",
        "events": [
            {
                "status": "in-transit",
                "description": "Shipment picked up by carrier.",
                "location": "Lagos, NG",
                "created_at": "2026-09-15T14:38:40.512Z"
            }
        ],
        "extras": {
            "tracking_number": "7412089553",
            "tracking_url": "https://track.terminal.africa/SH-40208776515"
        },
        "metadata": {
            "order_id": "ORD-10023"
        },
        "address_to": "AD-00632494668",
        "address_from": "AD-00632494667",
        "parcel": "PC-09857312356",
        "delivery_arranged": true,
        "delivery_picked_up": true,
        "created_at": "2026-09-15T09:02:11.903Z",
        "updated_at": "2026-09-15T14:38:40.512Z"
    }
}

shipment.awaiting-clearance

The shipment is held at customs. awaiting-clearance also appears in sub_statuses while the main status stays in-transit.

{
    "event": "shipment.awaiting-clearance",
    "data": {
        "shipment_id": "SH-40208776515",
        "user": "USER-27450202164",
        "status": "in-transit",
        "sub_statuses": ["awaiting-clearance"],
        "rate": "RT-64093387231",
        "carrier": "CA-85479996273",
        "tracking_number": "7412089553",
        "events": [
            {
                "status": "in-transit",
                "description": "Shipment is on hold - customs clearance required.",
                "location": "London, GB",
                "created_at": "2026-09-17T06:14:33.120Z"
            }
        ],
        "address_to": "AD-00632494668",
        "address_from": "AD-00632494667",
        "parcel": "PC-09857312356",
        "created_at": "2026-09-15T09:02:11.903Z",
        "updated_at": "2026-09-17T06:14:33.120Z"
    }
}

shipment.returned

{
    "event": "shipment.returned",
    "data": {
        "shipment_id": "SH-40208776515",
        "user": "USER-27450202164",
        "status": "returned",
        "sub_statuses": [],
        "rate": "RT-64093387231",
        "carrier": "CA-85479996273",
        "tracking_number": "7412089553",
        "events": [
            {
                "status": "returned",
                "description": "Shipment returned to shipper - recipient unavailable.",
                "location": "London, GB",
                "created_at": "2026-09-19T13:45:02.771Z"
            }
        ],
        "address_to": "AD-00632494668",
        "address_from": "AD-00632494667",
        "address_return": "AD-00632494667",
        "parcel": "PC-09857312356",
        "created_at": "2026-09-15T09:02:11.903Z",
        "updated_at": "2026-09-19T13:45:02.771Z"
    }
}

shipment.pending-cancellation

Cancellation has been requested but the carrier has not confirmed it.

{
    "event": "shipment.pending-cancellation",
    "data": {
        "shipment_id": "SH-40208776515",
        "user": "USER-27450202164",
        "status": "in-transit",
        "sub_statuses": ["pending-cancellation"],
        "rate": "RT-64093387231",
        "carrier": "CA-85479996273",
        "tracking_number": "7412089553",
        "events": [],
        "address_to": "AD-00632494668",
        "address_from": "AD-00632494667",
        "parcel": "PC-09857312356",
        "cancellation_request": true,
        "cancellation_reason": "Customer cancelled the order",
        "created_at": "2026-09-15T09:02:11.903Z",
        "updated_at": "2026-09-16T10:05:19.443Z"
    }
}

shipment.cancelled

{
    "event": "shipment.cancelled",
    "data": {
        "shipment_id": "SH-40208776515",
        "user": "USER-27450202164",
        "status": "cancelled",
        "sub_statuses": [],
        "rate": "RT-64093387231",
        "carrier": "CA-85479996273",
        "tracking_number": "7412089553",
        "events": [],
        "address_to": "AD-00632494668",
        "address_from": "AD-00632494667",
        "parcel": "PC-09857312356",
        "cancellation_request": true,
        "cancellation_reason": "Customer cancelled the order",
        "delivery_cancelled": true,
        "created_at": "2026-09-15T09:02:11.903Z",
        "updated_at": "2026-09-16T12:31:57.009Z"
    }
}

shipment.updated

Fires on any other change to an active shipment. Same shape; read events for what changed.

{
    "event": "shipment.updated",
    "data": {
        "shipment_id": "SH-40208776515",
        "user": "USER-27450202164",
        "status": "in-transit",
        "sub_statuses": [],
        "rate": "RT-64093387231",
        "carrier": "CA-85479996273",
        "tracking_number": "7412089553",
        "events": [
            {
                "status": "in-transit",
                "description": "Arrived at sort facility.",
                "location": "Dubai, AE",
                "created_at": "2026-09-16T22:11:04.330Z"
            }
        ],
        "address_to": "AD-00632494668",
        "address_from": "AD-00632494667",
        "parcel": "PC-09857312356",
        "created_at": "2026-09-15T09:02:11.903Z",
        "updated_at": "2026-09-16T22:11:04.330Z"
    }
}

shipment.created

Carries a fuller shipment object than the status events — close to what Get Shipment returns.

These are always stripped out and will never appear:

• extras.shipping_label and extras.aws_shipping_label_url (label bytes and internal storage keys)

• metadata.shipment_payload, metadata.carrier_shipment, metadata.selected_rate (carrier blobs)

• legs

{
    "event": "shipment.created",
    "data": {
        "shipment_id": "SH-40208776515",
        "user": "USER-27450202164",
        "status": "confirmed",
        "sub_statuses": [],
        "rate": "RT-64093387231",
        "carrier": "CA-85479996273",
        "tracking_number": "7412089553",
        "address_to": "AD-00632494668",
        "address_from": "AD-00632494667",
        "parcel": "PC-09857312356",
        "events": [
            {
                "status": "confirmed",
                "description": "Shipment arranged successfully by User.",
                "location": "Lagos, NG",
                "created_at": "2026-09-15T09:02:11.903Z"
            }
        ],
        "extras": {
            "tracking_number": "7412089553",
            "tracking_url": "https://track.terminal.africa/SH-40208776515",
            "carrier_tracking_url": "https://www.dhl.com/ng-en/home/tracking.html?tracking-id=7412089553",
            "shipping_label_url": "https://assets.terminal.africa/labels/SH-40208776515.pdf",
            "commercial_invoice_url": "https://assets.terminal.africa/invoices/SH-40208776515.pdf"
        },
        "metadata": {
            "order_id": "ORD-10023"
        },
        "pickup_date": "2026-09-15T14:00:00.000Z",
        "delivery_arranged": true,
        "created_at": "2026-09-15T09:02:11.903Z",
        "updated_at": "2026-09-15T09:02:11.903Z"
    }
}

shipment.customs_event

Fires when a customs delay is detected, and again when it is resolved. Read status to tell them apart — the event type is the same both times.

Detected

{
    "event": "shipment.customs_event",
    "data": {
        "shipment_id": "SH-40208776515",
        "status": "detected",
        "custom_delay_occured_at": "2026-09-17T06:14:33.120Z",
        "custom_delay_ended_at": null
    }
}

Resolved

{
    "event": "shipment.customs_event",
    "data": {
        "shipment_id": "SH-40208776515",
        "status": "resolved",
        "custom_delay_occured_at": "2026-09-17T06:14:33.120Z",
        "custom_delay_ended_at": "2026-09-18T08:52:16.401Z"
    }
}