Webhook Reservation Configuration

This document explains which reservation status changes we send to the partner/carrier webhook endpoint.

For live webhook traffic, see the simulator’s Webhook Log.

Webhook request format (Courier API -> Carrier)

The partner’s endpoint URL is configured in partner configuration. We deliver webhook events to that endpoint.

Default HTTP method: POST
Supported endpoint security option: static bearer token

Example payload (JSON)


{
  "reservationId": "RES-123456",
  "unitId": "UNIT-987",
  "status": "STOCKED",
  "changeTime": "2026-03-20T09:15:00.000Z",
  "flowType": "OUTLET",
  "barcode": "1234567890123",
  "docNumber": "DOC-10001",
  "expirationDate": "2026-03-22T09:15:00.000Z"
}

Payload fields

The webhook body uses this shape:

reservationId (string): reservation identification.
unitId (string): locker/unit identifier where the reservation exists.
status: new reservation status after transition.
changeTime (string, ISO date-time): when status change happened.
flowType: reservation flow direction/type.
barcode (string): package barcode.
docNumber (string, optional): document/reference number related to the reservation; can also be a manually written courier PIN (for example, when barcode scanning is not working).
expirationDate (string, optional, ISO date-time): reservation expiration timestamp, when applicable.

Key rule: webhook events are not for reservation create/update

When a partner or carrier creates a reservation, we do not send a webhook event that the reservation was created/reserved. The carrier learns the reservation details from the HTTP response to the create call.
When the carrier updates a reservation, we also do not send those update-driven transitions through the webhook endpoint. The carrier gets the authoritative state from the HTTP update call.

Webhook delivery is reserved for the lifecycle milestones listed below.

Status explanations (sent vs not sent)

EXPIRED (sent)

Automatically canceled reservation after expiration.

CANCELED (not sent)

Canceled reservation (typically initiated via reservation update/cancel calls). Since this is driven by the HTTP interaction, we do not emit a webhook event for it.

NEW (not sent)

Newly created reservation before any further processing. The carrier/partner should use the reservation create HTTP response instead of relying on webhook delivery.

RESERVED (not sent)

Reservation already created in Alfa3 and currently blocking a box, but not yet stocked. This is also created via the reservation create flow, so we do not send a webhook event indicating “reserved”.

INCOMPLETE (sent)

Partially stocked or package did not fit the box.

STOCKED (sent)

Stocked, ready to be picked up by the customer.

RETURNING (sent)

After the reservation becomes STOCKED, the customer is expected to collect the package within the usual grace period (typically about two days). If they do not collect it in time, the reservation transitions to RETURNING and will be picked up with the next driver login.

RETURNED (sent)

After the reservation is in RETURNING, the courier takes the package and brings it back to the depot; once it reaches the depot, the reservation transitions to RETURNED.

PICKED_UP (sent)

Picked up by the customer.

Summary: statuses that the webhook receives

EXPIRED, STOCKED, RETURNING, RETURNED, PICKED_UP, INCOMPLETE