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://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": "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

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)
eventsarrayJSON of the associated TrackingDetail objects
destination_eventsarrayJSON 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

events Object

attributetypespecification
objectarrayTrackingDetail
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_locationarrayThe location associated with the scan event

tracking_location Object

attributetypespecification
objectarrayTrackingLocation
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