Webhook

TrackShip can trigger webhook events to notify your system of 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 parameter.

Webhook that receives the Tracking updates from TrackShip

(POST) https://demostore.com/webhook/

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": "84cac6f02e418c3c8a3dc142fa3d2ef5",
  "order_id": "41086",
  "tracking_number": "9405511206203420254870",
  "tracking_provider": "usps",
  "tracking_event_status": "in_transit",
  "tracking_est_delivery_date": "2022-12-02 00:00:00",
  "tracking_destination_events": null,
  "origin_country": null,
  "destination_country": "US",
  "delivery_number": null,
  "delivery_provider": null,
  "shipping_service": "Priority Mail<SUP>&reg;</SUP>",
  "last_event_time": "2022-11-29 21:40:00",
  "events": [
    {
      "object": "TrackingDetail",
      "message": "Shipment Received, Package Acceptance Pending - MAGNA, UT",
      "description": "",
      "status": "pre_transit",
      "status_detail": "pre_transit",
      "datetime": "2022-11-29 16:52:00",
      "source": "USPS",
      "tracking_location": {
        "object": "TrackingLocation",
        "city": "MAGNA",
        "state": "UT",
        "country": "",
        "zip": "84044"
      }
    },
    {
      "object": "TrackingDetail",
      "message": "Accepted at USPS Origin Facility - MAGNA, UT",
      "description": "",
      "status": "in_transit",
      "status_detail": "in_transit",
      "datetime": "2022-11-29 20:25:00",
      "source": "USPS",
      "tracking_location": {
        "object": "TrackingLocation",
        "city": "MAGNA",
        "state": "UT",
        "country": "",
        "zip": "84044"
      }
    },
    {
      "object": "TrackingDetail",
      "message": "Arrived at USPS Regional Origin Facility - SALT LAKE CITY DISTRIBUTION CENTER, ",
      "description": "",
      "status": "in_transit",
      "status_detail": "in_transit",
      "datetime": "2022-11-29 21:40:00",
      "source": "USPS",
      "tracking_location": {
        "object": "TrackingLocation",
        "city": "SALT LAKE CITY DISTRIBUTION CENTER",
        "state": "",
        "country": "",
        "zip": ""
      }
    }
  ],
  "destination_events": null
}

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

Tracker Object

attribute	type	specification
user_key	string	User Key
order_id	string	Order Id
tracking_number	string	Tracking number for the parcel
tracking_provider	string	Tracking provider for the respective tracking number
tracking_event_status	string	The 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_est_delivery_date	datetime	The estimated delivery date provided by the carrier(if available)
events	array	JSON of the associated TrackingDetail objects
destination_events	array	JSON of the associated TrackingDetail objects(if available)
origin_country	string	Origin country code of the tracking
destination_country	string	Destination country code of the tracking
delivery_number	string	The assigned tracking number of the destination country.
delivery_provider	string	The assigned Shipping provider of the destination country.
shipping_service	string	Shipping service

events Object

attribute	type	specification
object	array	TrackingDetail
message	string	Description of the scan event
status	string	Status 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”
datetime	datetime	The timestamp when the tracking scan occurred
source	string	The original source of the information for this scan event, usually the carrier
tracking_location	array	The location associated with the scan event

tracking_location Object

attribute	type	specification
object	array	TrackingLocation
city	string	The city where the scan event occurred (if available)
state	string	The state where the scan event occurred (if available)
country	string	The country where the scan event occurred (if available)
zip	string	The postal code where the scan event occurred (if available)