Receive Tracking Information through a Webhook¶
On this page
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 theX-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:
|
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: |
eventTime |
String |
Required. The time posted by the carrier for the event. Format: |
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 |
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 |
estimatedDeliveryTime |
String |
The local time at the destination location that the parcel is expected to be delivered, specified in the |
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 |
eventLocation |
Required. The address the parcel was in at the time of the event. |
|
size |
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 |
deliveryTime |
String |
The local time at the destination when the parcel was delivered, specified in the |
deliveryTimeOffset |
String |
The UTC offset between the local time of the delivery and the time in UTC/GMT. The offset is specified in the |
destinationAddress |
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 |
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 |
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"
} ]
},
...
]
}