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 that Pitney Bowes can call via the HTTPS POST request described below, and you must provide credentials for the request to use when authenticating to the webhook. Once you have done so, Pitney Bowes sends the POST request as soon as tracking events are received from the carrier. The request body sends the data as an array containing a separate tracking event object for each 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. This is typically the labels you purchase from Pitney Bowes and tracking numbers that you have subscribed to through the Tracking API. The data can specify merchant shipper IDs upon request.

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 and Concurrency Limits limits to endpoints are scheduled for a future enhancement.

oAuth Expected Response

{
    "access_token": "m22wyEgfHlA0LudkGG9gG2xB04Cv", - Required
    "tokenType": "BearerToken", - Required
    "issuedAt": "1456851460568",
    "expiresIn": "35999", - Required
    "clientID": "3W8mOJ1Gh5lItmFCHzz82SZO9rc2EBwS",
    "org": "pitneybowes"
 }

Acknowledge Receipt of a POST Request

When your webhook receives the POST request sent by Pitney Bowes, send a response with the following:

• A standard HTTP Response Code should be sent in the header and in the statusCode field.

• In the response header, please include the X-PB-ReferenceId that was sent in the header of the POST request. Here is a sample: X-PB-ReferenceId: 6B29FC40-XXXX-YYYY-ZZZZ-00DD010662DA.

At the request level:

If the HTTP Response Code sent in the header has 2XX (where XX represents any number), Pitney Bowes will consider it as a Success. If the HTTP Response Code sent in the header has 400 it will be considered a BadRequest and all of the events in that request will not be retried. All HTTP Response Codes in the header that are not 2XX or 400 will be retried including all events at the following intervals:

1m, 5m, 10m, 30m, 1h, 2h, 4h, 8h, 16h After 16 hours, Pitney Bowes no longer sends the request.

At the individual event level:

If the statusCode field has 2XX (where XX represents any number), Pitney Bowes will consider that single event as a Success. If the statusCode field has 400 it will be considered a BadRequest and that event will not be retried. All statusCode field entries received that are not 2XX or 400 that individual event will be retried at the following intervals:

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

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

Sample Response

If your webhook endpoint supports multiple events, then in the response we need individual statusCode and errors fields for each submitted event. For example: If 2 events are sent in a single request, we expect below sample response, which states that first event is successfully processed and second one is rejected due to missing PackageStatus field. The errorId and message field content is at the discretion of the sender but must be formatted correctly.

 {
   "responses": [
      {
         "statusCode": 200,
         "errors": []
      },
      {
         "statusCode": 400,
         "errors": [
            {
               "errorId": 100005,
               "message": "Package status is required."
            }
         ]
      }
   ]
}

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 Shipment delayed Information Event
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	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. See PB Standardized Tracking Event Codes on the PB BOXdocs website.
StandardizedEventDescription	String	Required. The standardized event description provided by Pitney Bowes. See PB Standardized Tracking Event Codes on the PB BOXdocs website.
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": "PBCS",
        "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 2024 Pitney Bowes Inc. All rights reserved.