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 Standard 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 Standard

  • 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.

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

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
}