Parcel Events

Serverhttps://carrier.example.com/ooh

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

Parcel Updates: Get notifications about changes in parcel status.

Webhook for parcel updates

POST

https://carrier.example.com/ooh

/parcel-updates

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

RMG_UK only: before the consignee collection code expires, carrier-gateway sends the last parcel update again with shipmentStatus set to PARCEL_TO_BE_EXPIRED.

Webhook for parcel updates › Request Body

parcel_event

shipmentUid

string · required

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

lockerUid

string · required

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

carrierParcelId

string · required

The identifier of the parcel in the carrier's system

carrierLockerId

string · required

The identifier of the locker in the carrier's system

shipmentType

shipment_type · enum · required

The type of shipment.

Enum values:

LAST_MILE

ALTERNATIVE_DELIVERY

FIRST_MILE

RETURN

dimensionsStatus

dimensions_status · enum · required

The status of the parcel dimensions. The parcel API sends PARCEL_DIMENSIONS_EXCEEDED for a parcel that is too big; webhooks send PARCEL_DIMENSIONS_EXCEED.

Enum values:

PARCEL_DIMENSIONS_EXCEED

PARCEL_DIMENSIONS_EXCEEDED

PARCEL_DIMENSIONS_OK

PARCEL_DIMENSIONS_UNKNOWN

shipmentStatus

shipment_status · enum · required

The status of the shipment. LOCKED, UNLOCKED and CONSIGNEE_PAID are milestones in a parcel's events; they are never the parcel's shipmentStatus.

Enum values:

BOOKING_PRE_CHECK

BOOKING_REQUESTED

BOOKING_CREATED

BOOKING_CANCELLED

BOOKING_CANCELLATION_FAILED

BOOKING_EXPIRED

BOOKING_REJECTED_INVALID_LOCKER

BOOKING_REJECTED_PROVIDER_ERROR

object[] · required

carrierName

string · required

The name of the carrier

eventTimestamp

string · date-time · required

The timestamp of the parcel update

compartmentId

string | null

The identifier of the compartment assigned to the parcel

compartmentSize

string | null · enum

The size of the compartment assigned to the parcel

Enum values:

XXSMALL

XSMALL

SMALL

XMEDIUM

MEDIUM

LARGE

XLARGE

XXLARGE

mdmLocationId

string | null

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

barcodeContent

string | null

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

accessCodes

access_codes

Access codes for the parcel

consignee

consignee

The details of the consignee.

allocationType

allocation_type · enum

The allocation type of the shipment.

Enum values:

HARD_RESERVATION

SOFT_RESERVATION

providerName

string | null

The name of the locker network provider

providerLockerId

string | null

The identifier of the locker in the provider's system

shipmentSignature

signature

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

requireEasyAccess

boolean

Whether the parcel needs an accessible compartment. Absent when the platform did not say.

labelType

string | null · enum

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

Enum values:

LABELLESS

LABELED

referenceCode

string | null

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

secondaryShipmentId

string | null

A secondary identifier for the shipment, separate from carrierParcelId.

lockStatus

string | null · enum

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 values:

LOCKED

UNLOCKED

codAmount

integer | 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.

codCurrency

string | null

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

paymentType

string | null · enum

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 values:

CARD

FLIK

Webhook for parcel updates › Responses

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

No data returned

POST/parcel-updates

curl https://carrier.example.com/ooh/parcel-updates \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{
  "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",
  "accessCodes": {
    "consigneeCollection": "anyValidCode123",
    "consigneeCollectionCode": {
      "code": "anyValidCode123",
      "validUntil": "2025-01-27T12:00:00Z"
    }
  },
  "consignee": {
    "name": "John Doe",
    "email": "john.doe@google.com"
  },
  "events": [
    {
      "timestamp": "2025-08-20T00:00:00Z",
      "eventType": "CONSIGNEE_COLLECTED"
    }
  ],
  "allocationType": "HARD_RESERVATION",
  "carrierName": "GLS_DE",
  "providerName": "LOCKY_PT",
  "providerLockerId": "1178",
  "signature": "imageBase64StringHere",
  "shipmentSignature": {
    "imageBase64": "imageBase64StringHere",
    "format": ""
  },
  "requireEasyAccess": true,
  "labelType": "LABELLESS",
  "referenceCode": "LBL000000018",
  "secondaryShipmentId": "EXP-CODE-0001",
  "lockStatus": "LOCKED",
  "codAmount": 2450,
  "codCurrency": "EUR",
  "paymentType": "CARD",
  "eventTimestamp": "2025-08-20T00:00:00Z"
}'

Example Request Body

{
  "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",
  "accessCodes": {
    "consigneeCollection": "anyValidCode123",
    "consigneeCollectionCode": {
      "code": "anyValidCode123",
      "validUntil": "2025-01-27T12:00:00Z"
    }
  },
  "consignee": {
    "name": "John Doe",
    "email": "john.doe@google.com"
  },
  "events": [
    {
      "timestamp": "2025-08-20T00:00:00Z",
      "eventType": "CONSIGNEE_COLLECTED"
    }
  ],
  "allocationType": "HARD_RESERVATION",
  "carrierName": "GLS_DE",
  "providerName": "LOCKY_PT",
  "providerLockerId": "1178",
  "signature": "imageBase64StringHere",
  "shipmentSignature": {
    "imageBase64": "imageBase64StringHere",
    "format": ""
  },
  "requireEasyAccess": true,
  "labelType": "LABELLESS",
  "referenceCode": "LBL000000018",
  "secondaryShipmentId": "EXP-CODE-0001",
  "lockStatus": "LOCKED",
  "codAmount": 2450,
  "codCurrency": "EUR",
  "paymentType": "CARD",
  "eventTimestamp": "2025-08-20T00:00:00Z"
}

json

Example Responses

No example specified for this content type

Locker Events Collection Events