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 or null(signature)

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

requiresAccessibleCompartmentboolean
Example:true
labelTypestring or null

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

Enum:"LABELLESS""LABELED"null
Example:"LABELLESS"
referenceCodestring or null

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"
lockStatusstring or null

The current provider lock state of the parcel, when known. LOCKED means the consignee cannot collect the parcel (e.g. a cash-on-delivery payment is still pending); UNLOCKED means it can be collected. Absent when the parcel carries no lock state.

Enum:"LOCKED""UNLOCKED"null
Example:"LOCKED"
codAmountinteger or null, (int64)

The cash-on-delivery amount to collect from the consignee, in the currency's minor units (e.g. cents). Absent for parcels without cash-on-delivery.

Example:2450
codCurrencystring or null

ISO 4217 currency code for codAmount. Absent when codAmount is absent.

Example:"EUR"
paymentTypestring or null

The method the consignee paid a cash-on-delivery parcel with, as reported by the locker provider. The value set is country-specific: Slovenia (GLS_SI) is the only country live with cash-on-delivery today and reports CARD or FLIK, and the enum is extended as further countries are enabled. Absent for parcels without cash-on-delivery, before the payment is made, and when the provider reported no method or one outside the agreed set.

Enum:"CARD""FLIK"null
Example:"CARD"
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",
  "lockStatus": "LOCKED",
  "codAmount": 2450,
  "codCurrency": "EUR",
  "paymentType": "CARD",
  "eventTimestamp": "2025-08-20T00:00:00Z"
}

Responses

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