Legacy Tracking Webhook¶

Note

This page describes the legacy webhook service, which is deprecated. For the current webhook service, see Receive Tracking Information Through a Webhook.

Overview¶

Pitney Bowes provides a webhook service that sends tracking events for PB Expedited and PB labels printed through the Ecommerce APIs. To receive events, you must set up a webhook and provide Pitney Bowes with access. Pitney Bowes then sends tracking events specific to your developer ID every 30 minutes. The event data does not include merchant shipper IDs. Pitney Bowes sends events for shipments that have carrier set to the following:

USPS: PB Expedited
PBCS: PB Delivery
IMB: Services that print an IMb label

You can choose to receive events for a subset of the above by telling Pitney Bowes in advance.

Pitney Bowes sends tracking events to your webhook via an HTTPS POST request. The body of the request provides the tracking data. The request includes the X-PB-ReferenceId header, which contains a value you must pass back to acknowledge the receipt of the POST request.

Provide Pitney Bowes Access to Your Webhook¶

Create a webhook that can receive the Webhook Service POST Request. Once you have done so, 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 calls the PB service can make to the webhook hosted on this URL. Specify this value according to the maximum load that can be handled by the webhook shared with PB.

Pitney Bowes will not allow bursts above the maximum you specify.
Events: The maximum number of events per webhook.
Carriers (Optional): If you want to receive events only when the shipment’s carrier field is set to certain values, specify those values when contacting Pitney Bowes.

Responding to the POST Request¶

When your webhook receives the POST request sent by Pitney Bowes, 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.

Webhook Service POST Request¶

This section describes the POST request that Pitney Bowes sends to your webhook. To receive this POST request, you must provide Pitney Bowes access to the webhook, as described above.

POST Request Headers¶

The POST request includes the following headers.

Name

Description

Authorization

Authenticates to your webhook.

Content-Type

Indicates that the POST request sends a JSON request body.

X-PB-ReferenceId

The value you must pass back to acknowledge receipt of the POST request.

POST Request Body¶

The body of the POST request contains the following fields:

Name	Data Type	Description
eventList	Array[Event Object]	An array of unique tracking events. The array contains a separate Event Object for each tracking event reported. 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.
totalEvents	Number	The number of tracking events in the `eventList` array.

Event Object¶

Event objects appear in the eventList array. Each event object describes a tracking event in simple form.

Name	Data Type	Description
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[Scan Details Object]	Scan information from the barcode on the shipment label.

Scan Details Object¶

Name	Data Type	Description
eventDate	String	The date the event occurred, specified in the event’s time zone and in the YYYYMMDD date format.
eventTime	String	The time the event occurred, specified 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 event code provided by the carrier.
scanDescription	String	An event description provided by the carrier.
packageStatus	String	The package status as obtained from the barcode on the shipping label. Possible values: `Acceptance` `Delivered` `DeliveryAttempt` `Exception` `InTransit` `Manifest` `OutForDelivery` `PickedUp` `PickupMissed` `ReadyForPickup` `ReturnToSender`

Sample Webhook JSON Object¶

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

{
    "eventList": [ {
        "trackingNumber": "9400109898642304965461",
        "carrier": "USPS",
        "estimatedDeliveryDate": "20220326",
        "estimatedDeliveryTime": "123000",
        "scanDetails": {
            "eventDate": "20220324",
            "eventTime": "113400",
            "eventCity": "ATLANTA",
            "eventStateOrProvince": "GA",
            "postalCode": "30304",
            "country": null,
            "scanType": "OF",
            "scanDescription": "Out for Delivery",
            "packageStatus": "OutForDelivery"
        }
    },{
        "trackingNumber": "9400136895357844946618",
        "carrier": "USPS",
        "estimatedDeliveryDate": "20220324",
        "estimatedDeliveryTime": "114000",
        "scanDetails": {
            "eventDate": "20220324",
            "eventTime": "114200",
            "eventCity": "LAKELAND",
            "eventStateOrProvince": "FL",
            "postalCode": null,
            "country": null,
            "scanType": "01",
            "scanDescription": "Delivered, In/At Mailbox",
            "packageStatus": "Delivered"
        }
    },{
        "trackingNumber": "9405536895232850992862",
        "carrier": "USPS",
        "estimatedDeliveryDate": "20220324",
        "estimatedDeliveryTime": "122000",
        "scanDetails": {
            "eventDate": "20220324",
            "eventTime": "115113",
            "eventCity": "DAVENPORT",
            "eventStateOrProvince": "FL",
            "postalCode": null,
            "country": null,
            "scanType": "01",
            "scanDescription": "Delivered, In/At Mailbox",
            "packageStatus": "Delivered"
        }
    } ],
    "totalEvents": 3
}