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