Locker Open Deeplinks#

Webhooks are the way our backend notifies our clients about actions.

To correctly configure a webhook and start receiving notifications, our service provider must provide a link where they intend to receive these notifications. With this link and their client ID in Keycloak, our administrators will have everything necessary to create the new webhook.

To understand how it works, we will use our Locker Open flow as an example.

Locker Open Request for Dropoff#

Our service provider will generate a Locker Open Request for dropoff.

This will send a notification to the configured webhook of the service provider with information in this format:

{
  "timestamp": "2025-04-01T13:02:37",
  "event": "LOCKER_ASSIGNED",
  "data": {
    "timestamp": "2025-04-01T16:02:36.884285+00:00",
    "locker_id": 9,
    "locker_status": "rented",
    "tower_id": "0000000000000001",
    "source": "LOCKER_OPEN_LINK_CREATED",
    "reservation_id": null,
    "open_locker_token_id": null,
    "keypad_code": null,
    "client_info": null,
    "locker_open_request_id": 56,
    "locker_open_request_payload": {
      "extra": "data",
      "test": 123
    }
  }
}

Similarly, when the end user uses the link to perform the dropoff, another notification of the same type will be sent to the configured webhook:

One when the token to open the locker is created:

{
  "timestamp": "2025-04-01T13:12:57",
  "event": "LOCKER_OPERATION",
  "data": {
    "timestamp": "2025-04-01T16:12:57.521044+00:00",
    "locker_id": 9,
    "locker_status": "rented",
    "tower_id": "0000000000000001",
    "source": "LOCKER_TOKEN_CREATED",
    "reservation_id": null,
    "open_locker_token_id": 52,
    "keypad_code": null,
    "client_info": "Luis",
    "locker_open_request_id": null,
    "locker_open_request_payload": null
  }
}

Another when the token is finally used:

{
  "timestamp": "2025-04-01T13:15:47",
  "event": "LOCKER_OPERATION",
  "data": {
    "timestamp": "2025-04-01T16:15:45+00:00",
    "locker_id": 9,
    "locker_status": "occupied",
    "tower_id": "0000000000000001",
    "source": "LOCKER_TOKEN_USED",
    "reservation_id": null,
    "open_locker_token_id": 52,
    "keypad_code": null,
    "client_info": "Luis",
    "locker_open_request_id": 56,
    "locker_open_request_payload": {
      "extra": "data",
      "test": 123
    }
  }
}

Pickup Process#

The same process will be repeated during the pickup process, notifying this webhook that the user has finally retrieved their product from the locker.