PAparcelsapp
Webhooks

Receive tracking webhook

Parcels sends this JSON payload to the webhook_url supplied in POST /trackings when an individual shipment finishes or when the full request is complete. Delivery is scoped to that request; it is not a persistent shipment subscription. To check for carrier updates later, create another tracking request with the same tracking number and webhook_url.

The Parcels-Signature header has format t=<unix>,v1=<hex>. Verify it by computing HMAC_SHA256(secret, t + "." + raw_body) and comparing it to v1 with a timing-safe comparison. Reject signatures with an old timestamp, for example older than 5 minutes.

Webhook delivery is retried on network errors or HTTP 4xx/5xx responses. Return any 2xx status after you persist the payload.

post/parcels-webhook

Request

Headers

Parcels-Signaturestring required
Example:t=1782941000,v1=4a9c9b...

Timestamped HMAC signature: t=<unix>,v1=<hex>.

Request body

event'shipment_completed' | 'batch_completed' | 'tracking_error' required
request_idstring required
timestampstring date-time required
doneboolean required

Example request

{
  "event": "batch_completed",
  "request_id": "66f4f2c0e16b4c13bb7e0001",
  "timestamp": "2026-06-25T18:43:20.000Z",
  "done": true,
  "result": {
    "tracking_number": "9400111206213785678901",
    "state": "completed",
    "from_cache": true,
    "shipment": {
      "trackingId": "9400111206213785678901",
      "error": "TIMEDOUT",
      "accepted_fields": [
        "postal_code",
        "email",
        "phone"
      ],
      "status": "delivered",
      "origin": "United States",
      "destination": "United States",
      "originCode": "US",
      "destinationCode": "US",
      "fromAirport": "BRU",
      "toAirport": "DAR",
      "fromPort": "HKHKG",
      "toPort": "JPTYO",
      "pieces": 13,
      "weight": 385,
      "weight_unit": "kg",
      "volume": 1.67,
      "volume_unit": "m3",
      "flight_legs": [
        {
          "flight_number": "QR-8416",
          "origin": "DOH",
          "destination": "ALA",
          "status": "Booked",
          "scheduled_departure_date": "2026-09-02",
          "scheduled_departure": "2026-09-02T13:37:00+03:00",
          "scheduled_arrival": "2026-09-02T20:11:00+05:00",
          "actual_departure": "2026-09-02T13:37:00+03:00",
          "actual_arrival": "2026-09-02T20:25:00+05:00",
          "pieces": 34,
          "weight": 2608,
          "weight_unit": "kg",
          "volume": 32.07,
          "volume_unit": "m3"
        }
      ],
      "states": [
        {
          "state": "Delivered, In/At Mailbox",
          "location": "Austin, TX, United States",
          "date": "2026-06-25T18:42:00.000Z",
          "event_code": "DEP",
          "station": "DEL",
          "timezone": "Asia/Kolkata",
          "pieces": 13,
          "weight": 385,
          "weight_unit": "kg",
          "volume": 0.71,
          "volume_unit": "m3",
          "flight_number": "AI-2243",
          "flight_origin": "DOH",
          "flight_destination": "ALA",
          "scheduled_departure_date": "2026-09-02",
          "scheduled_departure": "2026-09-02T13:37:00+03:00",
          "scheduled_arrival": "2026-09-02T20:11:00+05:00",
          "actual_departure": "2026-09-02T13:37:00+03:00",
          "actual_arrival": "2026-09-02T20:25:00+05:00",
          "uld_number": "BT005AI"
        }
      ],
      "services": [
        {
          "slug": "usps",
          "name": "USPS"
        }
      ],
      "detectedCarrier": {
        "slug": "usps",
        "name": "USPS"
      },
      "detected": [
        0
      ],
      "attributes": [
        {
          "l": "origin",
          "val": "United States",
          "code": "US"
        }
      ],
      "externalTracking": [
        {
          "slug": "usps",
          "url": "https://tools.usps.com/go/TrackConfirmAction?tLabels=9400111206213785678901",
          "trackingId": "9400111206213785678901",
          "method": "GET"
        }
      ]
    },
    "delivery_estimate": {
      "model": {
        "version": "delivery-forecast-v1.2",
        "histogram_bucket_hours": 6
      },
      "error": {
        "minimum_sample_count": 8
      }
    }
  },
  "results": [
    {
      "tracking_number": "9400111206213785678901",
      "state": "completed",
      "from_cache": true,
      "shipment": {
        "trackingId": "9400111206213785678901",
        "error": "TIMEDOUT",
        "accepted_fields": [
          "postal_code",
          "email",
          "phone"
        ],
        "status": "delivered",
        "origin": "United States",
        "destination": "United States",
        "originCode": "US",
        "destinationCode": "US",
        "fromAirport": "BRU",
        "toAirport": "DAR",
        "fromPort": "HKHKG",
        "toPort": "JPTYO",
        "pieces": 13,
        "weight": 385,
        "weight_unit": "kg",
        "volume": 1.67,
        "volume_unit": "m3",
        "flight_legs": [
          {
            "flight_number": "QR-8416",
            "origin": "DOH",
            "destination": "ALA",
            "status": "Booked",
            "scheduled_departure_date": "2026-09-02",
            "scheduled_departure": "2026-09-02T13:37:00+03:00",
            "scheduled_arrival": "2026-09-02T20:11:00+05:00",
            "actual_departure": "2026-09-02T13:37:00+03:00",
            "actual_arrival": "2026-09-02T20:25:00+05:00",
            "pieces": 34,
            "weight": 2608,
            "weight_unit": "kg",
            "volume": 32.07,
            "volume_unit": "m3"
          }
        ],
        "states": [
          {
            "state": "Delivered, In/At Mailbox",
            "location": "Austin, TX, United States",
            "date": "2026-06-25T18:42:00.000Z",
            "event_code": "DEP",
            "station": "DEL",
            "timezone": "Asia/Kolkata",
            "pieces": 13,
            "weight": 385,
            "weight_unit": "kg",
            "volume": 0.71,
            "volume_unit": "m3",
            "flight_number": "AI-2243",
            "flight_origin": "DOH",
            "flight_destination": "ALA",
            "scheduled_departure_date": "2026-09-02",
            "scheduled_departure": "2026-09-02T13:37:00+03:00",
            "scheduled_arrival": "2026-09-02T20:11:00+05:00",
            "actual_departure": "2026-09-02T13:37:00+03:00",
            "actual_arrival": "2026-09-02T20:25:00+05:00",
            "uld_number": "BT005AI"
          }
        ],
        "services": [
          {
            "slug": "usps",
            "name": "USPS"
          }
        ],
        "detectedCarrier": {
          "slug": "usps",
          "name": "USPS"
        },
        "detected": [
          0
        ],
        "attributes": [
          {
            "l": "origin",
            "val": "United States",
            "code": "US"
          }
        ],
        "externalTracking": [
          {
            "slug": "usps",
            "url": "https://tools.usps.com/go/TrackConfirmAction?tLabels=9400111206213785678901",
            "trackingId": "9400111206213785678901",
            "method": "GET"
          }
        ]
      },
      "delivery_estimate": {
        "model": {
          "version": "delivery-forecast-v1.2",
          "histogram_bucket_hours": 6
        },
        "error": {
          "minimum_sample_count": 8
        }
      }
    }
  ],
  "error": {
    "code": "DESTINATION_COUNTRY_REQUIRED",
    "message": "destination_country is required unless carrier_hint is provided or the tracking number is an air waybill, ISO container number, or recognized ocean bill of lading.",
    "limit": 100,
    "current": 99,
    "requested_new": 2,
    "available": 1,
    "confirmation_url": "https://parcelsapp.com/api/v4/account/confirm/user%40example.com/token",
    "confirmation_expires_at": "2026-07-09T12:00:00.000Z",
    "rejected": [
      {
        "index": 1,
        "tracking_number": "1",
        "code": "INVALID_TRACKING_NUMBER",
        "message": "tracking_number is not valid for tracking."
      }
    ]
  }
}

Response

Return any 2xx status after persisting the webhook.

Changes

No recorded changes to this operation across all 1 revision of this API.