# Register a tracking webhook

Registers a webhook that will send HTTP notifications to you when the status of your tracked package changes. For more details on creating a webhook, see our guides on Webhooks and Tracking.

Endpoint: POST /tracks
Version: 2018-02-08
Security: APIKeyHeader

## Header parameters:

  - `SHIPPO-API-VERSION` (string)
    Optional string used to pick a non-default API version to use. See our API version guide.
    Example: "2018-02-08"

## Request fields (application/json):

  - `carrier` (string, required)
    Name of the carrier of the shipment to track.
    Example: "usps"

  - `metadata` (string)
    A string of up to 100 characters that can be filled with any additional information you want to attach to the object.
    Example: "Order 000123"

  - `tracking_number` (string, required)
    Tracking number to track.
    Example: "9205590164917312751089"

## Response 200 fields (application/json):

  - `address_from` (object)
    The sender address with city, state, zip and country information.

  - `address_from.city` (string)
    Example: "Las Vegas"

  - `address_from.country` (string)
    Example: "US"

  - `address_from.state` (string)
    Example: "NV"

  - `address_from.zip` (string)
    Example: "89101"

  - `address_to` (object)
    The recipient address with city, state, zip and country information.

  - `carrier` (string, required)
    Name of the carrier of the shipment to track. See Carriers.
    Example: "usps"

  - `eta` (string)
    The estimated time of arrival according to the carrier, this might be updated by carriers during the life of the shipment.

  - `messages` (array, required)

  - `metadata` (string)
    A string of up to 100 characters that can be filled with any additional information you want to attach to the object.
    Example: "Order 000123"

  - `original_eta` (string)
    The estimated time of arrival according to the carrier at the time the shipment first entered the system.
    Example: "2021-07-23T00:00:00Z"

  - `servicelevel` (object)
    Contains details regarding the service level for the given rate.

  - `servicelevel.name` (string)
    Name of the Rate's servicelevel, e.g. International Priority or Standard Post. 
A servicelevel commonly defines the transit time of a Shipment (e.g., Express vs. Standard), along with other properties. 
These names vary depending on the provider.
    Example: "Priority Mail Express"

  - `servicelevel.terms` (string)
    Further clarification of the service.

  - `servicelevel.token` (string)
    Token of the Rate's servicelevel, e.g. usps_priority or fedex_ground. 
See servicelevels.
    Example: "usps_priority_express"

  - `servicelevel.extended_token` (string)
    Unique, extended version of the Service Level "token". 
Guaranteed to be unique across all Service Levels, and may help offer insight into the specific Service Level it describes.

  - `servicelevel.parent_servicelevel` (object)
    Contains details regarding the service level for the given rate.

  - `tracking_history` (array, required)
    A list of tracking events, following the same structure as tracking_status. 
It contains a full history of all tracking statuses, starting with the earlier tracking event first.

  - `tracking_history.location` (object)
    An object containing zip, city, state and country information of the tracking event.

  - `tracking_history.object_created` (string, required)

  - `tracking_history.object_id` (string, required)

  - `tracking_history.object_updated` (string, required)

  - `tracking_history.status` (string, required)
    Indicates the high level status of the shipment.
    Enum: "UNKNOWN", "PRE_TRANSIT", "TRANSIT", "DELIVERED", "RETURNED", "FAILURE"

  - `tracking_history.substatus` (object)
    A finer-grained classification of the tracking event.

  - `tracking_history.substatus.code` (string, required)
    A code that represents the substatus of the shipment. See the Event Definitions for more information.
    Example: "information_received"

  - `tracking_history.substatus.text` (string, required)
    A human-readable description of the substatus. See the Event Definitions for more information.
    Example: "Information about the package received."

  - `tracking_history.substatus.action_required` (boolean, required)
    Indicates whether the substatus requires action from the shipper or recipient to complete delivery.

  - `tracking_history.status_date` (string)
    Date and time when the carrier scanned this tracking event. This is displayed in UTC.
    Example: "2016-07-23T00:00:00Z"

  - `tracking_history.status_details` (string, required)
    The human-readable description of the status.
    Example: "Your shipment has been delivered at the destination mailbox."

  - `tracking_number` (string, required)
    Tracking number to track.
    Example: "9205590164917312751089"

  - `tracking_status` (object)
    The latest tracking information of this shipment.

  - `transaction` (string)
    The object_id of the transaction associated with this tracking object. 
This field is visible only to the object owner of the transaction.