Skip to content

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.