Webhook

TrackShip can trigger webhook events to notify your system for every new tracking event.

Securing Webhooks

We currently support only HTTPS URLs, so you have security by using an SSL-enabled URL. But keep in mind that your API endpoint is going to be wide-open on the internet, and you do not want others to be able to submit random data to your system. At this time, aside from trying to keep the URL private, we also pass your API key in the webhook API call and you can check on your end that the API Key exists in the header and/or body parameter.

Webhook that receives the Tracking updates from TrackShip

(POST) https://example.com/webhook.php

Headers

trackship-api-key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-type: application/json
accept: application/json

Request Body

The request body will be sent from TrackShip to your webhook URL.

{
    "user_key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "order_id": "2800",
    "tracking_number": "9274890278835136903138",
    "tracking_provider": "usps",
    "tracking_event_status": "in_transit",
    "tracking_event_date": "2022-04-03 05:58:06",
    "tracking_est_delivery_date": null,
    "tracking_events": "[{\"object\":\"TrackingDetail\",\"message\":\"Picked Up by Shipping Partner, USPS Awaiting Item - DETROIT, MI\",\"description\":\"\",\"status\":\"in_transit\",\"status_detail\":\"in_transit\",\"datetime\":\"2022-03-30 17:06:00\",\"source\":\"USPS\",\"tracking_location\":{\"object\":\"TrackingLocation\",\"city\":\"DETROIT\",\"state\":\"MI\",\"country\":\"\",\"zip\":\"48216\"}},{\"object\":\"TrackingDetail\",\"message\":\"Arrived Shipping Partner Facility, USPS Awaiting Item - GLENDALE HEIGHTS, IL\",\"description\":\"\",\"status\":\"in_transit\",\"status_detail\":\"in_transit\",\"datetime\":\"2022-04-01 05:34:00\",\"source\":\"USPS\",\"tracking_location\":{\"object\":\"TrackingLocation\",\"city\":\"GLENDALE HEIGHTS\",\"state\":\"IL\",\"country\":\"\",\"zip\":\"60139\"}},{\"object\":\"TrackingDetail\",\"message\":\"Departed Shipping Partner Facility, USPS Awaiting Item - GLENDALE HEIGHTS, IL\",\"description\":\"\",\"status\":\"in_transit\",\"status_detail\":\"in_transit\",\"datetime\":\"2022-04-01 13:46:00\",\"source\":\"USPS\",\"tracking_location\":{\"object\":\"TrackingLocation\",\"city\":\"GLENDALE HEIGHTS\",\"state\":\"IL\",\"country\":\"\",\"zip\":\"60139\"}},{\"object\":\"TrackingDetail\",\"message\":\"Arrived Shipping Partner Facility, USPS Awaiting Item - YORK, PA\",\"description\":\"\",\"status\":\"in_transit\",\"status_detail\":\"in_transit\",\"datetime\":\"2022-04-02 03:15:00\",\"source\":\"USPS\",\"tracking_location\":{\"object\":\"TrackingLocation\",\"city\":\"YORK\",\"state\":\"PA\",\"country\":\"\",\"zip\":\"17406\"}},{\"object\":\"TrackingDetail\",\"message\":\"Departed Shipping Partner Facility, USPS Awaiting Item - YORK, PA\",\"description\":\"\",\"status\":\"in_transit\",\"status_detail\":\"in_transit\",\"datetime\":\"2022-04-02 09:39:00\",\"source\":\"USPS\",\"tracking_location\":{\"object\":\"TrackingLocation\",\"city\":\"YORK\",\"state\":\"PA\",\"country\":\"\",\"zip\":\"17406\"}},{\"object\":\"TrackingDetail\",\"message\":\"Arrived USPS Facility - HARRISBURG, PA\",\"description\":\"\",\"status\":\"in_transit\",\"status_detail\":\"in_transit\",\"datetime\":\"2022-04-02 12:48:00\",\"source\":\"USPS\",\"tracking_location\":{\"object\":\"TrackingLocation\",\"city\":\"HARRISBURG\",\"state\":\"PA\",\"country\":\"\",\"zip\":\"17112\"}},{\"object\":\"TrackingDetail\",\"message\":\"Departed USPS Facility - HARRISBURG, PA\",\"description\":\"\",\"status\":\"in_transit\",\"status_detail\":\"in_transit\",\"datetime\":\"2022-04-02 16:17:00\",\"source\":\"USPS\",\"tracking_location\":{\"object\":\"TrackingLocation\",\"city\":\"HARRISBURG\",\"state\":\"PA\",\"country\":\"\",\"zip\":\"17112\"}},{\"object\":\"TrackingDetail\",\"message\":\"Arrived at USPS Regional Facility - WARRENDALE PA DISTRIBUTION CENTER, \",\"description\":\"\",\"status\":\"in_transit\",\"status_detail\":\"in_transit\",\"datetime\":\"2022-04-02 20:37:00\",\"source\":\"USPS\",\"tracking_location\":{\"object\":\"TrackingLocation\",\"city\":\"WARRENDALE PA DISTRIBUTION CENTER\",\"state\":\"\",\"country\":\"\",\"zip\":\"\"}},{\"object\":\"TrackingDetail\",\"message\":\"Arrived USPS Regional Facility - WARRENDALE PA DISTRIBUTION CENTER, \",\"description\":\"\",\"status\":\"in_transit\",\"status_detail\":\"in_transit\",\"datetime\":\"2022-04-02 20:45:00\",\"source\":\"USPS\",\"tracking_location\":{\"object\":\"TrackingLocation\",\"city\":\"WARRENDALE PA DISTRIBUTION CENTER\",\"state\":\"\",\"country\":\"\",\"zip\":\"\"}}]",
    "tracking_destination_events": null,
    "origin_country": null,
    "destination_country": "US",
    "delivery_number": null,
    "delivery_provider": null,
    "shipping_service": "Parcel Select Lightweight"
}

Response code should be 200 if not TrackShip will trigger another webhook again in 2 hours.

Tracker Object

attributetypespecification
user_keystringUser Key
order_idstringOrder Id
tracking_numberstringTracking number for the parcel
tracking_providerstringTracking provider for the respective tracking number
tracking_event_statusstringThe current status of the package, possible values are “unknown”, “pre_transit”, “in_transit”, “out_for_delivery”, “delivered”, “available_for_pickup”, “return_to_sender”, “failure”, “cancelled”
tracking_event_datedatetimeDate and time the tracking was updated.
tracking_est_delivery_datedatetimeThe estimated delivery date provided by the carrier(if available)
tracking_eventsstringJSON of the associated TrackingDetail objects
tracking_destination_eventsdatetimeJSON of the associated TrackingDetail objects(if available)
origin_countrystringOrigin country code of the tracking
destination_countrystringDestination country code of the tracking
delivery_numberstringThe assigned tracking number of the destination country.
delivery_providerstringThe assigned Shipping provider of the destination country.
shipping_servicestringShipping service

TrackingDetail Object

attributetypespecification
objectstringTrackingDetail
messagestringDescription of the scan event
statusstringStatus of the package at the time of the scan event, possible values are “unknown”, “pre_transit”, “in_transit”, “out_for_delivery”, “delivered”, “available_for_pickup”, “return_to_sender”, “failure”, “cancelled”
datetimedatetimeThe timestamp when the tracking scan occurred
sourcestringThe original source of the information for this scan event, usually the carrier
tracking_locationTrackingLocationThe location associated with the scan event

TrackingLocation Object

attributetypespecification
objectstringTrackingLocation
citystringThe city where the scan event occurred (if available)
statestringThe state where the scan event occurred (if available)
countrystringThe country where the scan event occurred (if available)
zipstringThe postal code where the scan event occurred (if available)
On this page