Receive Tracking Information via a Tracking Webhook

Overview

Pitney Bowes provides a webhook service through which you can receive tracking events for PB Expedited labels and PB Standard labels printed through the PB Shipping APIs. The service runs every 30 minutes and sends tracking events specific to your developer ID. The tracking events do not specify the merchant’s shipper ID. The service supports shipments that have carrier set to either of the following:

  • USPS (PB Expedited)

  • PBCS (PB Standard)

Note

The webhook service sends tracking information only for labels printed through the PB Shipping APIs.

The webhook service sends tracking events via an HTTP POST request to a URL you have provided. The POST request sends the data through the Event List Object in the body of the request. The request also sends an X-PB-ReferenceId header that contains a value you pass back to acknowledge receipt of the POST request.

To receive the POST request, you must configure a webhook.

Configure the Webhook

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.

Respond to the POST Request

When your webhook receives the webhook service’s POST request, send a response with the following:

  • An HTTP 2XX status code.

  • An X-PB-ReferenceId header that contains the value sent in the X-PB-ReferenceId header of the POST request.

If you do not return the expected response, Pitney Bowes retries the POST request three times.

Event List 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 code for the scan event. See Tracking Event Codes.

        scanDescription

String

The description of the scan event. See Tracking Event Codes.

        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": "20210610",
        "estimatedDeliveryTime": null,
        "scanDetails": {
            "eventDate": "20210606",
            "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": "20210610",
        "estimatedDeliveryTime": null,
        "scanDetails": {
            "eventDate": "20210606",
            "eventTime": "223200000",
            "eventCity": "MARIETTA",
            "eventStateOrProvince": "GA",
            "postalCode": "30062",
            "country": null,
            "scanType": null,
            "scanDescription": "ORIGIN ACCEPTANCE",
            "packageStatus": "InTransit"
        }
    },{
        "trackingNumber": "9400109898642304965461",
        "carrier": "USPS",
        "estimatedDeliveryDate": "20210610",
        "estimatedDeliveryTime": null,
        "scanDetails": {
            "eventDate": "20210606",
            "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": "20210610",
        "estimatedDeliveryTime": null,
        "scanDetails": {
            "eventDate": "20210607",
            "eventTime": "090800000",
            "eventCity": "ATLANTA",
            "eventStateOrProvince": "GA",
            "postalCode": "30354",
            "country": null,
            "scanType": null,
            "scanDescription": "DEPART USPS FACILITY",
            "packageStatus": "InTransit"
        }
    } ],
    "totalEvents": 4
}