End-to-End WebHook Setup

This guide provides an overview of how to use Pitney Bowes webhook services for tracking events. Pitney Bowes supports tracking for shipments processed both on-platform (shipments handled by Pitney Bowes) and off-platform (shipments handled by other platforms).

On-Platform Tracking Events

Overview

These events are generated for shipments processed by Pitney Bowes. Developers can configure a webhook to receive tracking events automatically. Tracking numbers for on-platform shipments are automatically subscribed, and once a webhook is set up, related events are broadcast automatically.

Setup Instructions:

  • Configure webhooks to automate tracking event notifications.
  • Provide an accurate URL and credentials during setup.
  • Ensure secure communication via OAuth or Basic Authentication.

Off-Platform Tracking Events

Overview

These events are for shipments processed by other platforms but tracked through Pitney Bowes. Developers must subscribe to tracking numbers to receive updates for off-platform shipments.

Setup Instructions:

  • Configure webhooks to automate tracking event notifications.
  • Provide an accurate URL and credentials during setup.
  • Ensure secure communication via OAuth or Basic Authentication.
  • Verify that the carrier is supported by Pitney Bowes before subscribing.
  • Provide valid tracking numbers and carrier information to receive updates.

Webhook Configuration

Developers can configure webhooks to receive tracking events as they occur. This allows real-time tracking updates for shipments associated with their account.

Steps to Configure Webhook:

1. Get Applicable Events

Use the Get Applicable Event List for Webhook Configuration API to retrieve a list of trackable events.
  • Endpoint: /api/v1/webhook/events
  • Security: bearerAuth
  • Response: A list of event IDs and names, such as:
    • Manifest
    • Acceptance
    • InTransit
    • DeliveryAttempt
    • OutForDelivery
    • Delivered
    • Exception
    • ReturnToSender
    • ReadyForPickup
    • PickupMissed
    • PickedUp

Sample Request:

Copy
Copied
curl -i -X GET \
  https://api-sandbox.sendpro360.pitneybowes.com/webhook/api/v1/events \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Sample Response:

Copy
Copied
[
    {
        "eventId": "Manifest",
        "name": "Manifest"
    },
    {
        "eventId": "Acceptance",
        "name": "Acceptance"
    },
    {
        "eventId": "InTransit",
        "name": "InTransit"
    },
    {
        "eventId": "DeliveryAttempt",
        "name": "DeliveryAttempt"
    },
    {
        "eventId": "OutForDelivery",
        "name": "OutForDelivery"
    },
    {
        "eventId": "Delivered",
        "name": "Delivered"
    },
    {
        "eventId": "Exception",
        "name": "Exception"
    },
    {
        "eventId": "ReturnToSender",
        "name": "ReturnToSender"
    },
    {
        "eventId": "ReadyForPickup",
        "name": "ReadyForPickup"
    },
    {
        "eventId": "PickupMissed",
        "name": "PickupMissed"
    },
    {
        "eventId": "PickedUp",
        "name": "PickedUp"
    }
]

2. Create Webhook Configuration

Use the Create Webhook Configuration API to set up a webhook. Provide the events, URL, and authentication details.
  • Required Fields:
    • name: The name of the webhook.
    • type: Must be set to tracking.
    • events: Array of event IDs to track.
    • url: The webhook URL where tracking events will be sent.
    • authParams: Authentication details:
      • Custom: Pass apiKey and headerName.
      • Basic: Pass clientId and secret.
  • Optional Fields:
  • timeOut: Timeout duration in seconds for webhook responses.
  • status: Defaults to active. Use inactive to deactivate.
  • Endpoint:
    • /api/v1/webhook/configure
  • Response:
    • Returns a unique webHookConfigID for updating webhook details.

Sample Request:

Copy
Copied
curl -i -X POST \
  https://api-sandbox.sendpro360.pitneybowes.com/webhook/api/v1/webhookConfig \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "webhook1",
    "type": "tracking",
    "events": ["Manifest", "InTransit", "Delivered"],
    "url": "https://webhook.com",
    "timeOut": 5,
    "status": "active",
    "authParams": {
      "authType": "custom",
      "apiKey": "JsuG7jk",
      "headerName": "webhook1"
    }
  }'

Sample Response:

Copy
Copied
{
    "webHookConfigID": "D6yEwX1zaZjj",
    "name": "dev_webhook1",
    "type": "tracking",
    "events": [
        "Manifest",
        "InTransit",
        "Delivered"
    ],
    "url": "https://webhook.com",
    "authParams": {
        "authType": "custom",
        "apiKey": "JsuG7jk",
        "headerName": "webhook1"
    },
    "timeOut": 5,
    "status": "active",
    "developerPartnerId": "sacxxxx"
}

3. Receive Tracking Events

Once the webhook is set up, Pitney Bowes sends tracking events to your configured URL as they occur.

Expected Behavior:

  • Authorization: Webhooks use OAuth or Basic Authentication for secure communication.
  • Response Acknowledgment: Acknowledge POST requests by returning the X-PB-developerPartnerId in the response.
  • Retries: If Pitney Bowes does not receive a 2XX status code, it retries the request at intervals up to 16 hours.

Off-Platform Tracking Events

For Off-Platform shipments, tracking details must be subscribed to using the Subscribe Tracking Details API.

  • Carrier Support: Tracking is available only if Pitney Bowes supports the specified carrier service.
  • Unsubscribe event: To stop receiving updates for a tracking number, use the same API with subscribe set to false.

Steps to Subscribe Tracking Details:

1. Subscribe to Tracking Details

Use the Subscribe Tracking Details API to request tracking updates for an off-platform shipment.

Required Fields:

  • trackingNumber: The shipment's tracking number.
  • carrier: The carrier's ID (e.g., USPS, UPS, FedEx).
  • subscribe: Set to true to enable tracking updates.
  • Endpoint: /api/v1/subscribe/tracking
  • Security: bearerAuth

Sample Request:

Copy
Copied
curl -i -X GET \
  'https://api-sandbox.sendpro360.pitneybowes.com/shippingtracking/api/v1/track/{trackingNumber}/subscribe?carrier=USPS&subscribe=true' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'X-PB-Developer-Partner-ID: string'

Sample Response:

Copy
Copied
{
    "message": "Tracking number subscribed successfully",
    "trackingEvents": {
      "carrier": "FEDEX",
      "currentLocation": {
        "city": "Miami",
        "country": "US",
        "description": "Delivered",
        "postalCode": "33122",
        "stateOrProvince": "FL"
      },
      "currentStatus": {
        "carrierEventCode": "DL",
        "carrierEventDescription": "Delivered",
        "eventCode": "AWP- Awaiting Pickup",
        "eventDate": "2023-06-28T16:55:00.000Z",
        "eventDescription": "Delivered",
        "eventLocation": {
          "city": "Miami",
          "country": "US",
          "description": "",
          "postalCode": "33122",
          "stateOrProvince": "FL"
        },
        "status": "Delivered"
      },
      "deliveryDate": "2023-06-28T16:55:00.000Z",
      "deliveryProofUrl": "",
      "estimatedDeliveryDate": "1901-01-01T00:00:00.000Z",
      "serviceCode": "",
      "serviceName": "FedEx Ground",
      "shipDate": "1901-01-01T00:00:00.000Z",
      "trackingHistory": [
        {
          "carrierEventCode": "DL",
          "carrierEventDescription": "Delivered",
          "eventCode": "DLD",
          "eventDate": "2023-06-28T16:55:00.000Z",
          "eventDescription": "Delivered",
          "eventLocation": {
            "city": "Miami",
            "country": "US",
            "description": "",
            "postalCode": "33122",
            "stateOrProvince": "FL"
          },
          "status": "Delivered"
        }
      ]
    }
  }

2. Receive Tracking Details

Once subscribed, Pitney Bowes broadcast tracking information for the off-platform shipment, such as the current status, estimated delivery date, and event history.