Subscriptions and Parcel Webhooks

[email protected]

By using the ‘WebhookUrl’ field or the subscriptions, you can specify a callback URL to get an update when the parcel is in updated status. If the ‘WebhookUrl’ is set when creating a parcel or if a subscription exists, the API will send an HTTP POST request to that URL with a JSON payload containing the Parcel Id when the parcel status is changed. The kind of event that was triggered will be passed in a header called "Event-Type" where possible events are:

parcel_created
parcel_scanned_at_checkpoint
parcel_not_scanned_at_checkpoint
parcel_scanned_at_pickup
parcel_not_scanned_at_pickup
parcel_scanned_at_delivery
parcel_not_scanned_at_delivery
parcel_linked_to_order
parcel_unlinked_from_order
parcel_profile_updated

[ParcelCreated]
Header: Event-Type: "parcel_created"

Body:

{
  "eventType": "parcel_created",
  "parcelId": "parcel-abc123",
  "parcelProfileId": "019a0823-4259-7cf7-b498-2a1de17203e2",
  "source": "Order",
  "barcode": "1Z999AA10123456784",
  "creationDate": "2026-06-08T10:00:00Z",
  "expiryDate": "2026-07-08T10:00:00Z",
  "metadata": {
    "fragile": true,
    "weight": 2.5
  }
}

[ParcelScannedAtCheckpoint]
Header: Event-Type: "parcel_scanned_at_checkpoint"

Body:

{
  "eventType": "parcel_scanned_at_checkpoint",
  "parcelId": "parcel-abc123",
  "parcelProfileId": "019a0823-4259-7cf7-b498-2a1de17203e2",
  "activityId": "activity-001",
  "timestamp": "2026-06-08T11:00:00Z",
  "checkpointId": "checkpoint-001",
  "routeId": "route-001",
  "orderId": "order-001",
  "segmentOrderId": "segment-001",
  "itemId": "item-001",
  "userLocation": { "lat": 45.5017, "lng": -73.5673 },
  "exceptionCodes": ["exc-001"]
}

[ParcelNotScannedAtCheckpoint]
Header: Event-Type: "parcel_not_scanned_at_checkpoint"

Body:

{
  "eventType": "parcel_not_scanned_at_checkpoint",
  "parcelId": "parcel-abc123",
  "parcelProfileId": "019a0823-4259-7cf7-b498-2a1de17203e2",
  "activityId": "activity-002",
  "timestamp": "2026-06-08T11:05:00Z",
  "checkpointId": "checkpoint-001",
  "routeId": "route-001",
  "orderId": "order-001",
  "segmentOrderId": "segment-001",
  "itemId": "item-001",
  "userLocation": { "lat": 45.5017, "lng": -73.5673 },
  "exceptionCodes": ["exc-002"]
}

[ParcelScannedAtPickup]
Header: Event-Type: "parcel_scanned_at_pickup"

Body:

{
  "eventType": "parcel_scanned_at_pickup",
  "parcelId": "parcel-abc123",
  "parcelProfileId": "019a0823-4259-7cf7-b498-2a1de17203e2",
  "activityId": "activity-003",
  "timestamp": "2026-06-08T12:00:00Z",
  "orderId": "order-001",
  "segmentOrderId": "segment-001",
  "itemId": "item-001",
  "userLocation": { "lat": 45.5017, "lng": -73.5673 },
  "exceptionCodes": []
}

[ParcelNotScannedAtPickup]
Header: Event-Type: "parcel_not_scanned_at_pickup"

Body:

{
  "eventType": "parcel_not_scanned_at_pickup",
  "parcelId": "parcel-abc123",
  "parcelProfileId": "019a0823-4259-7cf7-b498-2a1de17203e2",
  "activityId": "activity-004",
  "timestamp": "2026-06-08T12:05:00Z",
  "orderId": "order-001",
  "segmentOrderId": "segment-001",
  "itemId": "item-001",
  "userLocation": { "lat": 45.5017, "lng": -73.5673 },
  "exceptionCodes": ["exc-003"]
}

[ParcelScannedAtDelivery]
Header: Event-Type: "parcel_scanned_at_delivery"

Body:

{
  "eventType": "parcel_scanned_at_delivery",
  "parcelId": "parcel-abc123",
  "parcelProfileId": "019a0823-4259-7cf7-b498-2a1de17203e2",
  "activityId": "activity-005",
  "timestamp": "2026-06-08T15:00:00Z",
  "orderId": "order-001",
  "segmentOrderId": "segment-001",
  "itemId": "item-001",
  "userLocation": { "lat": 45.5017, "lng": -73.5673 },
  "exceptionCodes": []
}

[ParcelNotScannedAtDelivery]
Header: Event-Type: "parcel_not_scanned_at_delivery"

Body:

{
  "eventType": "parcel_not_scanned_at_delivery",
  "parcelId": "parcel-abc123",
  "parcelProfileId": "019a0823-4259-7cf7-b498-2a1de17203e2",
  "activityId": "activity-006",
  "timestamp": "2026-06-08T15:05:00Z",
  "orderId": "order-001",
  "segmentOrderId": "segment-001",
  "itemId": "item-001",
  "userLocation": { "lat": 45.5017, "lng": -73.5673 },
  "exceptionCodes": ["exc-004"]
}

[ParcelLinkedToOrder]
Header: Event-Type: "parcel_linked_to_order"

Body:

{
  "eventType": "parcel_linked_to_order",
  "parcelId": "parcel-abc123",
  "parcelProfileId": "019a0823-4259-7cf7-b498-2a1de17203e2",
  "activityId": "activity-007",
  "timestamp": "2026-06-08T09:00:00Z",
  "orderId": "order-001",
  "itemId": "item-001"
}

[ParcelUnlinkedFromOrder]
Header: Event-Type: "parcel_unlinked_from_order"

Body:

{
  "eventType": "parcel_unlinked_from_order",
  "parcelId": "parcel-abc123",
  "parcelProfileId": "019a0823-4259-7cf7-b498-2a1de17203e2",
  "activityId": "activity-008",
  "timestamp": "2026-06-08T09:30:00Z",
  "orderId": "order-001",
  "itemId": "item-001"
}

[ParcelProfileUpdated]
Header: Event-Type: "parcel_profile_updated"

Body:

{
  "eventType": "parcel_profile_updated",
  "parcelId": "parcel-abc123",
  "parcelProfileId": "019a0823-4259-7cf7-b498-2a1de17203e2",
  "statusesCompleted": [
    { "completion": { "position": 1, "nbOfCompletions": 1 }, "activityId": "activity-009" }
  ]
}