Skip to content

Parcel Events

This webhook endpoint is designed to push updates about parcels handling events.

  • Parcel Updates: Get notifications about changes in parcel status.
Webhooks

Webhook for parcel updates
Webhook

Request

Webhook to push parcel updates to any URL provided by the carrier. This endpoint allows carriers to receive real-time updates about parcels.

Security
ApiKeyAuth
Bodyapplication/json

Information about parcel updates

shipmentUidstring

The unique identifier of the parcel shipment in the GLS/NXT Platform

Example:"anyParcelId123"
lockerUidstring

The unique identifier of the locker in the GLS/NXT Platform

Example:"anyLockerId123"
carrierParcelIdstring

The identifier of the parcel in the carrier's system

Example:"anyCarrierParcelId123"
carrierLockerIdstring or null

The identifier of the locker in the carrier's system

Example:"Locker1"
compartmentIdstring or null

The identifier of the compartment assigned to the parcel

Example:"A-01"
compartmentSizestring or null

The size of the compartment assigned to the parcel

Enum:"XXSMALL""XSMALL""SMALL""XMEDIUM""MEDIUM""LARGE""XLARGE""XXLARGE""ULARGE""UULARGE"
Example:"MEDIUM"
mdmLocationIdstring or null

Specific to certain carriers only. The MDM location identifier associated with the parcel locker

Example:"123456"
barcodeContentstring or null

Specific to certain carriers only. The barcode content associated with the parcel

Example:"LBL000000018"
shipmentTypestring(shipment_type)

The type of shipment.

Enum:"LAST_MILE""ALTERNATIVE_DELIVERY""FIRST_MILE""RETURN"
Example:"LAST_MILE"
dimensionsStatusstring(dimensions_status)

The status of the parcel dimensions.

Enum:"PARCEL_DIMENSIONS_EXCEED""PARCEL_DIMENSIONS_OK""PARCEL_DIMENSIONS_UNKNOWN"
Example:"PARCEL_DIMENSIONS_OK"
shipmentStatusstring(shipment_status)

The status of the shipment.

Enum:"BOOKING_PRE_CHECK""BOOKING_REQUESTED""BOOKING_CREATED""BOOKING_CANCELLED""BOOKING_CANCELLATION_FAILED""BOOKING_EXPIRED""BOOKING_REJECTED_INVALID_LOCKER""BOOKING_REJECTED_PROVIDER_ERROR""BOOKING_REJECTED_LOCKER_IS_FULL""BOOKING_REJECTED_NO_FREE_FITTING_COMPARTMENT"
Example:"CONSIGNEE_COLLECTED"
isFinalboolean
Example:true
accessCodesobject or null(access_codes)

Access codes for the parcel

consigneeobject or null(consignee)

The details of the consignee.

eventsArray of objects(parcel_events)
allocationTypestring(allocation_type)

The allocation type of the shipment.

Enum:"HARD_RESERVATION""SOFT_RESERVATION"
Example:"HARD_RESERVATION"
carrierNamestring or null

The name of the carrier

Example:"GLS_DE"
providerNamestring or null

The name of the locker network provider

Example:"LOCKY_PT"
providerLockerIdstring or null

The identifier of the locker in the provider's system

Example:"1178"
shipmentSignatureobject(signature)

A Base64-encoded image representing the consignee's signature, captured upon parcel collection

requiresAccessibleCompartmentboolean
Example:true
labelTypestring

Label mode for the shipment. LABELLESS means no printed label is used and LABELED means a printed label is used.

Enum:"LABELLESS""LABELED"
Example:"LABELLESS"
referenceCodestring

Reference code scanned by driver during pickup of the labelless parcel. This field is only relevant for LABELLESS shipments.

Example:"LBL000000018"
secondaryShipmentIdstring or null

A secondary identifier for the shipment, separate from carrierParcelId.

Example:"EXP-CODE-0001"
eventTimestampstring, (date-time)

The timestamp of the parcel update

Example:"2025-08-20T00:00:00Z"
Payload
{
  "shipmentUid": "anyParcelId123",
  "lockerUid": "anyLockerId123",
  "carrierParcelId": "anyCarrierParcelId123",
  "carrierLockerId": "Locker1",
  "compartmentId": "A-01",
  "compartmentSize": "MEDIUM",
  "mdmLocationId": "123456",
  "barcodeContent": "LBL000000018",
  "shipmentType": "LAST_MILE",
  "dimensionsStatus": "PARCEL_DIMENSIONS_OK",
  "shipmentStatus": "CONSIGNEE_COLLECTED",
  "isFinal": true,
  "accessCodes": {
    "consigneeCollection": "anyValidCode123",
    "consigneeCollectionCode": { … }
  },
  "consignee": {
    "name": "John Doe",
    "email": "[email protected]"
  },
  "events": [
    { … }
  ],
  "allocationType": "HARD_RESERVATION",
  "carrierName": "GLS_DE",
  "providerName": "LOCKY_PT",
  "providerLockerId": "1178",
  "shipmentSignature": {
    "imageBase64": "imageBase64StringHere",
    "format": ""
  },
  "requiresAccessibleCompartment": true,
  "labelType": "LABELLESS",
  "referenceCode": "LBL000000018",
  "secondaryShipmentId": "EXP-CODE-0001",
  "eventTimestamp": "2025-08-20T00:00:00Z"
}

Responses

Return a 200 status to indicate that the data was received successfully.