Locker Events

Serverhttps://carrier.example.com/ooh

This webhook endpoint is designed to push events about locker updates.

New Locker: An event will be pushed when a new Locker is created.
Locker status: An event is pushed when the locker status changes (enabled/disabled).

Webhook for locker updates

POST

https://carrier.example.com/ooh

/locker-updates

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

Webhook for locker updates › Request Body

The locker data that carrier-gateway sends when a locker of the carrier is created or changes. carrier-gateway omits an optional field when it has no value; it never sends `null`.

webhook_update_request

uid

string · required

The internal unique identifier assigned to the locker.

webhook_locker_carrier · required

The details of the locker on the Carrier's system.

webhook_locker_provider · required

The details of the locker on the Provider's system.

webhook_location · required

Details about the geographical location of the locker.

features · required

Features available in the locker.

metadata[] · required

Additional metadata associated with the locker.

compartment[] · required

A list of different compartment types available in the locker.

eventTimestamp

string · date-time · required

The timestamp of the locker status update.

opening_hours

Locker availability schedule.

Conditional constraints (enforced server-side, not by the generated client):

If accessMode is SCHEDULED, weeklySchedule MUST be provided and non-empty.
If accessMode is ALWAYS, weeklySchedule MUST be omitted.

webhook_locker_owner

The owner of the locker. Absent when the platform has no owner for the locker.

Webhook for locker updates › Responses

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

No data returned

POST/locker-updates

curl https://carrier.example.com/ooh/locker-updates \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{
  "uid": "1002377838",
  "carrier": {
    "lockerName": "Berlin Locker 01",
    "lockerId": "XR1003",
    "activationDate": "2025-08-20T00:00:00Z",
    "status": "ACTIVE"
  },
  "provider": {
    "name": "KEBA",
    "lockerModel": "Model 1",
    "lockerVersion": "v2.1",
    "lockerName": "BLOQ-Berlin-12045-001",
    "lockerUid": "PROVIDER_LOCKER_ABC123",
    "status": "ACTIVE"
  },
  "location": {
    "street": "Main Street",
    "streetNumber": "1",
    "postalCode": "90210",
    "city": "Berlin",
    "lon": -118.2437,
    "lat": 34.0522,
    "countryCode": "DE",
    "locationType": "indoor",
    "locationSubtype": "GAS_STATION"
  },
  "features": {
    "hasScreen": true,
    "hasPinPad": true,
    "hasPinBarcodeReader": false
  },
  "metadata": [
    {
      "key": "maxWeightCapacity",
      "value": "50kg"
    }
  ],
  "compartmentTypes": [
    {
      "size": "MEDIUM",
      "count": 4,
      "height": 400,
      "width": 400,
      "length": 600
    }
  ],
  "eventTimestamp": "2025-08-20T00:00:00Z",
  "openingHours": {
    "accessMode": "ALWAYS",
    "weeklySchedule": [
      {
        "weekday": "MONDAY",
        "periods": [
          {
            "open": "08:00",
            "close": "20:00"
          }
        ]
      }
    ],
    "exceptions": [
      {
        "startDate": "2026-12-25",
        "endDate": "2026-12-25",
        "isClosed": true,
        "schedule": [
          {
            "weekday": "MONDAY",
            "periods": [
              {
                "open": "10:00",
                "close": "16:00"
              }
            ]
          }
        ]
      }
    ]
  },
  "owner": {
    "name": "GLS",
    "type": "CARRIER"
  }
}'

Example Request Body

{
  "uid": "1002377838",
  "carrier": {
    "lockerName": "Berlin Locker 01",
    "lockerId": "XR1003",
    "activationDate": "2025-08-20T00:00:00Z",
    "status": "ACTIVE"
  },
  "provider": {
    "name": "KEBA",
    "lockerModel": "Model 1",
    "lockerVersion": "v2.1",
    "lockerName": "BLOQ-Berlin-12045-001",
    "lockerUid": "PROVIDER_LOCKER_ABC123",
    "status": "ACTIVE"
  },
  "location": {
    "street": "Main Street",
    "streetNumber": "1",
    "postalCode": "90210",
    "city": "Berlin",
    "lon": -118.2437,
    "lat": 34.0522,
    "countryCode": "DE",
    "locationType": "indoor",
    "locationSubtype": "GAS_STATION"
  },
  "features": {
    "hasScreen": true,
    "hasPinPad": true,
    "hasPinBarcodeReader": false
  },
  "metadata": [
    {
      "key": "maxWeightCapacity",
      "value": "50kg"
    }
  ],
  "compartmentTypes": [
    {
      "size": "MEDIUM",
      "count": 4,
      "height": 400,
      "width": 400,
      "length": 600
    }
  ],
  "eventTimestamp": "2025-08-20T00:00:00Z",
  "openingHours": {
    "accessMode": "ALWAYS",
    "weeklySchedule": [
      {
        "weekday": "MONDAY",
        "periods": [
          {
            "open": "08:00",
            "close": "20:00"
          }
        ]
      }
    ],
    "exceptions": [
      {
        "startDate": "2026-12-25",
        "endDate": "2026-12-25",
        "isClosed": true,
        "schedule": [
          {
            "weekday": "MONDAY",
            "periods": [
              {
                "open": "10:00",
                "close": "16:00"
              }
            ]
          }
        ]
      }
    ]
  },
  "owner": {
    "name": "GLS",
    "type": "CARRIER"
  }
}

json

Example Responses

No example specified for this content type

Parcel Events