Receive Tracking Information through a Webhook

Set up a Webhook

Pitney Bowes provides a webhook service through which you can receive tracking events as they arrive in the PB tracking system. To receive events, you must set up a webhook URL that Pitney Bowes can call via an HTTPS POST request and must provide Pitney Bowes access to the URL, as described below. Once you have done so, Pitney Bowes issues the POST request whenever tracking events arrive in the tracking system. The request payload contains an array of tracking event objects. Each object is a separate tracking event.

The POST request also includes a header with a value you must pass back to acknowledge receipt of the POST request. You must pass back the value of X-PB-ReferenceId header, as described below in Acknowledge Receipt of a POST Request.

Pitney Bowes sends tracking data specific to your developer ID. The data does not specify merchant shipper IDs.

Provide Pitney Bowes Access to the Webhook

Once you have set up the webhook, 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 authentication mechanism and the credentials for authenticating to the webhook. The PB Webhook Service supports OAuth and Basic authentication. Depending on which you use, provide the following:

    For OAuth, provide the following:

    • Token URL: The URL for retrieving a token.

    • Client ID: The ID to use when generating the token.

    • Client Secret: The secret to use when generating the token.

    • Scope: Any API restrictions the token may have.

    For Basic Authentication, provide the following:

    • Username

    • Password

  • Throttling Limits: Let us know if you would like the webhook service to limit the TPS (Transaction Per Second) to the webhook.

  • Concurrency Limits: Let us know if you would like the webhook service to limit the concurrent calls to the webhook.

Acknowledge Receipt of a 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 at the following intervals:

1m, 5m, 10m, 30m, 1h, 2h, 4h, 8h, 16h

After 16 hours, Pitney Bowes no longer sends the request.

POST Request

This section describes the headers and payload sent by the POST request.

Request Headers

Name


Description

Authorization

Authenticates to your webhook.

Content-Type

Indicates the payload is formatted as JSON.

X-PB-ReferenceId

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

Payload

The POST request sends the trackingEvents array, which contains a separate tracking event object for each tracking event reported. A shipment’s tracking number can appear multiple times in the 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.

Tracking Event Object

The trackingEvents array returns tracking event objects. Tracking event objects contain the following fields.

Field


Type

Description

trackingNumber

String

Required. The tracking number returned by the carrier.

referenceNumber

String

A merchant-specified number.

smartLabelBarcode

String

The Pitney Bowes barcode created for the parcel, if applicable.

carrier

String

Required. The carrier that handled the parcel.

packageStatus

String

Required. The parcel’s status in the PB tracking system. Possible values are:

  • Manifest

  • Acceptance

  • InTransit

  • DeliveryAttempt

  • OutForDelivery

  • Delivered

  • Exception

  • ReturnToSender

  • ReadyForPickup

  • PickupMissed

  • PickedUp

eventDescription

String

Required. The event description provided by the carrier. See the carrier’s documentation. For Pitney Bowes or USPS, see Tracking Event Codes.

eventDate

String

Required. The date posted by the carrier for the event. Format: YYYY-MM-DD

eventTime

String

Required. The time posted by the carrier for the event. Format: HH:MM:SS

eventTimeOffset

String

Required. The UTC offset between the local time of the event and the time in UTC/GMT. The offset is specified in the ±hh:mm format.

eventCode

String

Required. The event code provided by the carrier. See the carrier’s documentation. For Pitney Bowes or USPS, see Tracking Event Codes.

StandardizedEventCode

String

Required. The standardized event code provided by Pitney Bowes. For the list of Pitney Bowes standardized event codes, see the Event Code Mapping table on the Pitney Bowes Standard Tracking Codes page.

StandardizedEventDescription

String

Required. The standardized event description provided by Pitney Bowes. For the list of Pitney Bowes standardized event descriptions, see the Event Code Mapping table on the Pitney Bowes Standard Tracking Codes page.

eventLeg

String

Used internally by Pitney Bowes.

serviceName

String

The carrier’s name for the service.

serviceCode

String

The carrier’s code or name for the service.

estimatedDeliveryDate

String

The date the parcel is expected to be delivered at the destination location, specified in the YYYY-MM-DD format.

estimatedDeliveryTime

String

The local time at the destination location that the parcel is expected to be delivered, specified in the HH:MM:SS format.

estimatedDeliveryTimeOffset

String

The UTC offset between the local time of the estimated delivery and the time in UTC/GMT. The offset is specified in the ±hh:mm format.

eventLocation

Event Location Object

Required. The address the parcel was in at the time of the event.

size

Size Object

Required. The parcel’s weight and dimensions.

authorizedAgent

String

Used internally by Pitney Bowes.

trackingUrl

String

The final-mile carrier’s URL for tracking the parcel.

latitude

String

The latitude at which this event took place.

longitude

String

The longitude at which this event took place.

locationUnit

String

The latitude and longitude at which this event took place, specified in degrees minutes seconds (DMS). For example:

41°24’12.2”N 2°10’26.5”E

deliveryDate

String

The date at the destination when the parcel was delivered, specified in the YYYY-MM-DD format.

deliveryTime

String

The local time at the destination when the parcel was delivered, specified in the HH:MM:SS format.

deliveryTimeOffset

String

The UTC offset between the local time of the delivery and the time in UTC/GMT. The offset is specified in the ±hh:mm format.

destinationAddress

Destination Address Object

Required. The address to which the parcel is delivered.

shipFromZipCode

String

The postal code the parcel originated from.

shipFromZipCode4

String

The specific delivery route within the delivery area.

additionalAttributes

Array[Object]

For future use.

additionalAttributes.name

String

For future use.

additionalAttributes.value

String

For future use.

additionalAttributes.type

String

For future use.

Event Location Object

Field


Type

Description

city

String

The city the parcel was in at the time of the event.

stateOrProvince

String

The name or 2-letter code of the state or province the parcel was in at the time of the event.

countyOrRegion

String

The county or region the parcel was in at the time of the event.

country

String

The name, 2-letter code, or 3-letter code of the country the parcel was in at the time of the event.

postalCode

String

The postal code the parcel was in at the time of the event.

PostalCode4

String

The specific delivery route within the delivery area.

description

String

An event description provided by the carrier. For example, “front porch”.

Size Object

Field


Type

Description

weight

String

The parcel’s weight.

weightUnit

String

The unit of measure for weight field.

length

String

The parcel’s length.

width

String

The parcel’s width.

height

String

The parcel’s height.

unitOfMeasurement

String

The unit of measure for the length, width, and height fields.

Destination Address Object

Field


Type

Description

city

String

The city the parcel is delivered to.

stateOrProvince

String

The name or 2-letter code of the state or province the parcel is delivered to.

countyOrRegion

String

The county or region the parcel is delivered to.

country

String

The name, 2-letter code, or 3-letter code of the country the parcel is delivered to.

postalCode

String

The postal code the parcel is delivered to.

PostalCode4

String

The specific delivery route within the delivery area.

description

String

An event description provided by the carrier. For example, “front porch”.

Sample Payload for PB Expedited (USPS)

{
    "trackingEvents": [ {
        "trackingNumber": "9405509999999999275926",
        "referenceNumber": null,
        "smartLabelBarcode": null,
        "carrier": "USPS",
        "packageStatus": "Delivered",
        "eventDescription": "Delivered, In/At Mailbox",
        "eventDate": "2023-01-04",
        "eventTime": "14:32:00",
        "eventTimeOffset": "-08:00",
        "eventCode": "01",
        "standardizedEventCode": "DLD",
        "StandardizedEventDescription": "Delivered, In/At Mailbox",
        "eventLeg": "",
        "serviceName": "First-Class Package Service",
        "serviceCode": "001",
        "estimatedDeliveryDate": null,
        "estimatedDeliveryTime": null,
        "estimatedDeliveryTimeOffset": null,
        "eventLocation": {
            "city": "Salem",
            "stateOrProvince": "OR",
            "countyOrRegion": "",
            "country": "",
            "postalCode": "97306",
            "PostalCode4": "7011",
            "description": ""
        },
        "size": {
            "weight": "4.00",
            "weightUnit": "OZ",
            "length": null,
            "width": null,
            "height": null,
            "unitOfMeasurement": null
        },
        "authorizedAgent": null,
        "trackingUrl": null,
        "latitude": null,
        "longitude": null,
        "locationUnit": null,
        "deliveryDate": "2023-01-04",
        "deliveryTime": "14:32:00",
        "deliveryTimeOffset": "-08:00",
        "destinationAddress": {
            "city": "Salem",
            "stateOrProvince": "OR",
            "countyOrRegion": "",
            "country": "",
            "postalCode": "97306",
            "PostalCode4": "7011",
            "description": ""
        },
        "shipFromZipCode": "96278",
        "shipFromZipCode4": "2050",
        "additionalAttributes": [ {
            "name": null,
            "value": null,
            "type": null
        } ]
    },
    ...
    ]
}

Sample Payload for PB Standard Return

{
    "trackingEvents": [ {
        "trackingNumber": "420569019999999999999033371906",
        "requestedIdentifier": null,
        "referenceNumber": "123456789",
        "smartLabelBarcode": "7251077899999999999999982125W",
        "carrier": "PBS",
        "packageStatus": "InTransit",
        "eventDescription": "Arrived at Facility",
        "eventDate": "2023-01-28",
        "eventTime": "16:28:37",
        "eventTimeOffset": "-06:00",
        "eventCode": "IPS",
        "standardizedEventCode": "IPS",
        "standardizedEventDescription": "Arrived at Facility",
        "eventType": null,
        "serviceName": "Parcel Return Service",
        "serviceCode": "RP",
        "estimatedDeliveryDate": null,
        "estimatedDeliveryTime": null,
        "estimatedDeliveryTimeOffset": null,
        "eventLocation": {
            "city": "Irving",
            "stateOrProvince": "TX",
            "country": "US",
            "postalCode": "75038",
            "description": ""
        },
        "size": {
            "weight": "1.0158",
            "weightUom": "lbs",
            "length": "",
            "width": "",
            "height": "",
            "unitOfMeasurement": null
        },
        "trackingUrl": null,
        "latitude": null,
        "longitude": null,
        "locationUnit": "",
        "deliveryDate": null,
        "deliveryTime": null,
        "deliveryTimeOffset": null,
        "destinationAddress": {
            "city": "",
            "stateOrProvince": "",
            "country": "",
            "postalCode": "67846",
            "description": null
        },
        "shipFromZipCode": "77864",
        "shipFromZipCode4": "77864-3111",
        "shipperId": "9024324564",
        "integratorId": "12345678",
        "partnerId": "12345678",
        "clientId": "",
        "serviceDirection": "",
        "additionalAttributes": [ {
            "name": "EventLeg",
            "value": "FML",
            "type": "String"
        } ]
    },
    ...
    ]
}