> For the complete documentation index, see [llms.txt](https://docs.terminal.africa/tship/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.terminal.africa/tship/miscallaneous/sample-webhook-event-payloads/shipment.md). # Shipment Sample payloads for every shipment webhook event. Shipment webhooks come in three shapes. Which one you get depends on the event.
EventsPayload
shipment.updated, shipment.in-transit, shipment.delivered, shipment.cancelled, shipment.returned, shipment.awaiting-clearance, shipment.pending-cancellationA lean tracking snapshot.
shipment.createdA fuller shipment object.
shipment.customs_eventA 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](/tship/shipment/get-shipment.md) 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 ```javascript { "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. ```javascript { "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`. ```javascript { "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 ```javascript { "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. ```javascript { "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 ```javascript { "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. ```javascript { "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](/tship/shipment/get-shipment.md) 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` ```javascript { "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 ```javascript { "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 ```javascript { "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" } } ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.terminal.africa/tship/miscallaneous/sample-webhook-event-payloads/shipment.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.