Receive Tracking Information via a Tracking Webhook

Note

This feature is not yet in general release. To participate in the Beta program, please contact Support.

Overview

Pitney Bowes provides a webhook service through which you can receive tracking events for the USPS labels you have printed through the PB Shipping APIs. The service runs every hour and sends tracking events received from USPS for your developer ID. The service sends the events in JSON format via an HTTP POST request. The request includes the X-PB-ReferenceId header containing a value you must pass back in your response. Your response must include both the X-PB-ReferenceId header, set to the specified value, and include an HTTP 2XX status code. If you do not return the expected response, Pitney Bowes retries the webhook three times.

The tracking events are specific to your developer ID. The tracking events do not specify the merchant’s shipper ID.

Configuration

To configure the webhook, you must contact Pitney Bowes and provide the following information:

  • Host: The server hosting the webhook.

  • URL: The full URL of the webhook. The URL must use HTTPS.

  • Credentials: The username and password for authenticating to the webhook using basic authentication.

  • Threads: The maximum number of concurrent requests the webhook can support.

    Pitney Bowes will not allow bursts above the maximum you specify.

  • Events: The maximum number of events per webhook.

JSON Object

The body of the webhook’s POST request contains a JSON object with the fields described here. The eventList array contains a separate object for each tracking event reported. The object describes an event in its simplest form.

A shipment’s tracking number can appear multiple times in the eventList array. Each occurrence of the tracking number records a separate event for the shipment. To view all the events associated with a shipment, locate all occurrences of the shipment’s tracking number in the array.

Name
Data Type Description
eventList Array [object] An array of unique tracking events.
    trackingNumber String The package identifier for the parcel.
    carrier String The carrier for the tracking event.
    estimatedDeliveryDate String The delivery date in the destination time zone, specified in the YYYYMMDD date format.
    estimatedDeliveryTime String The delivery time in the destination time zone, specified in the 24-hour time format.
    scanDetails Array[Object] Scan information from the barcode on the shipment label.
        eventDate String The date the event occurred in the event’s time zone, specified in the YYYYMMDD date format.
        eventTime String The time the event occurred in the event’s time zone.
        eventCity String The city where the event occurred.
        eventStateorProvince String The state or province where the event occurred.
        postalCode String The postal code where the event occurred.
        Country String The country where the event occurred.
        scanType String The type of scan event, as provided by USPS.
        ScanDescription String The description of the scan event, as provided by USPS.
        packageStatus String The package status.
totalEvents Number The number of tracking events in the eventList array.

Sample Webhook JSON Object

The following is an example webhook JSON object with four tracking events.

{
    "eventList": [ {
        "trackingNumber": "9400109898642304965461",
        "carrier": "USPS",
        "estimatedDeliveryDate": "20190610",
        "estimatedDeliveryTime": null,
        "scanDetails": {
            "eventDate": "20190606",
            "eventTime": "224700000",
            "eventCity": "ATLANTA",
            "eventStateOrProvince": "GA",
            "postalCode": "30304",
            "country": null,
            "scanType": null,
            "scanDescription": "ACCEPTED AT USPS FACILITY  10",
            "packageStatus": "InTransit"
        }
    },{
        "trackingNumber": "9400109898642304965461",
        "carrier": "USPS",
        "estimatedDeliveryDate": "20190610",
        "estimatedDeliveryTime": null,
        "scanDetails": {
            "eventDate": "20190606",
            "eventTime": "223200000",
            "eventCity": "MARIETTA",
            "eventStateOrProvince": "GA",
            "postalCode": "30062",
            "country": null,
            "scanType": null,
            "scanDescription": "ORIGIN ACCEPTANCE",
            "packageStatus": "InTransit"
        }
    },{
        "trackingNumber": "9400109898642304965461",
        "carrier": "USPS",
        "estimatedDeliveryDate": "20190610",
        "estimatedDeliveryTime": null,
        "scanDetails": {
            "eventDate": "20190606",
            "eventTime": "100300000",
            "eventCity": "MARIETTA",
            "eventStateOrProvince": "GA",
            "postalCode": "30062",
            "country": null,
            "scanType": null,
            "scanDescription": "SHIPPING LBL CREATED  USPS AWAITS ITEM",
            "packageStatus": "Manifest"
        }
    },{
        "trackingNumber": "9400109898642304965478",
        "carrier": "USPS",
        "estimatedDeliveryDate": "20190610",
        "estimatedDeliveryTime": null,
        "scanDetails": {
            "eventDate": "20190607",
            "eventTime": "090800000",
            "eventCity": "ATLANTA",
            "eventStateOrProvince": "GA",
            "postalCode": "30354",
            "country": null,
            "scanType": null,
            "scanDescription": "DEPART USPS FACILITY",
            "packageStatus": "InTransit"
        }
    } ],
    "totalEvents": 4
}