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"
        } ]
    },
    ...
    ]
}

• Legacy Webhook

 
 
 
 

• next
• previous |

© Copyright 2023, PB.