BoxLatviaDevelopers
Get access
Guides

Webhooks

Instead of asking the API again and again, let BoxLatvia tell you. A webhook is an address of yours that BoxLatvia calls with a small JSON message the moment something happens to your boxes.

#The events

EventSent whenWhat you get
order.placedan order for one of your boxes is paidthe whole order, with the renter's contact details
order.cancelleda paid order is refunded or cancelledthe whole order, now with its new status
box.availability_changedthe number of free units of a box changes because of an order (down when it is placed, up when it is cancelled)the box and its new number of free units
Note
The two order events contain the renter's name, e-mail and phone. They are personal data: use them only to hand over the box and serve the rental. Subscribing to them needs the scope orders:read as well as webhooks:write. box.availability_changed has no personal data.

#Quick start

  1. #Subscribe

    Register your address and choose the events. Store the secret from the answer: it is shown only once.

    Subscribe
    curl -X POST "$API/v1/webhooks" \
      -u "$CLIENT_ID:$CLIENT_SECRET" \
      -H "Content-Type: application/json" \
      -d '{
      "url": "https://erp.imantastorage.example/webhooks/boxlatvia",
      "events": [
        "order.placed",
        "order.cancelled",
        "box.availability_changed"
      ],
      "description": "Imanta ERP"
    }'
    201 CreatedLocation: https://api.boxlatvia.lv/v1/webhooks/cb3cf942-3e09-4b76-9b89-0143c09a8ae9
    {
      "id": "cb3cf942-3e09-4b76-9b89-0143c09a8ae9",
      "url": "https://erp.imantastorage.example/webhooks/boxlatvia",
      "description": "Imanta ERP",
      "events": [
        "order.placed",
        "order.cancelled",
        "box.availability_changed"
      ],
      "status": "active",
      "consecutive_failures": 0,
      "disabled_reason": null,
      "disabled_at": null,
      "last_success_at": null,
      "last_failure_at": null,
      "created_at": "2026-11-14T09:00:01.000Z",
      "updated_at": "2026-11-14T09:00:01.000Z",
      "secret": "whsec_8Fh2kQ0pXm4TnV7cYd1LrB9sAe5ZuWjG"
    }
  2. #Receive and verify

    Your address receives a POST with a JSON body. Verify the signature, then answer with a 2xx status within 10 seconds. Do the real work afterwards: put the event in a queue and answer at once.

  3. #Send a test

    Check the whole chain without waiting for a real order.

    A test event
    curl -X POST "$API/v1/webhooks/cb3cf942-3e09-4b76-9b89-0143c09a8ae9/test" \
      -u "$CLIENT_ID:$CLIENT_SECRET"
    202
    {
      "event_id": "evt_e45a0c9d-e02d-43d0-bc2c-bb9eb9b3cd09",
      "status": "queued",
      "message": "A test event is on its way. See GET /v1/webhooks/{id}/deliveries for the result."
    }
    The result

    The delivery history shows what happened to each event and why an attempt failed.

    curl "$API/v1/webhooks/cb3cf942-3e09-4b76-9b89-0143c09a8ae9/deliveries?limit=10" \
      -u "$CLIENT_ID:$CLIENT_SECRET"
    200 OK
    {
      "data": [
        {
          "id": "dlv_2ff29879-e014-4073-a557-dc223bc2b152",
          "event_id": "evt_70992594-5e8d-4f77-aa18-b5d5661ec959",
          "event_type": "webhook.test",
          "status": "succeeded",
          "attempts": 1,
          "next_attempt_at": null,
          "last_attempt_at": "2026-11-14T09:20:03.000Z",
          "last_status_code": 200,
          "last_error": null,
          "last_duration_ms": 214,
          "delivered_at": "2026-11-14T09:20:03.000Z",
          "created_at": "2026-11-14T09:20:00.000Z"
        },
        {
          "id": "dlv_bf376349-5c7e-40c5-83c4-b19cb4d93561",
          "event_id": "evt_3bb11835-8fb0-49fc-93ff-a7346c491a37",
          "event_type": "box.availability_changed",
          "status": "pending",
          "attempts": 2,
          "next_attempt_at": "2026-11-14T09:21:00.000Z",
          "last_attempt_at": "2026-11-14T09:15:40.000Z",
          "last_status_code": 503,
          "last_error": "the receiver answered HTTP 503",
          "last_duration_ms": 411,
          "delivered_at": null,
          "created_at": "2026-11-14T09:10:00.000Z"
        },
        {
          "id": "dlv_9496eae2-46fa-447d-bb3a-c18dc835a072",
          "event_id": "evt_58e9121f-e7ad-4371-804a-4b9eec3b53d3",
          "event_type": "order.placed",
          "status": "failed",
          "attempts": 8,
          "next_attempt_at": null,
          "last_attempt_at": "2026-11-14T09:50:00.000Z",
          "last_status_code": 500,
          "last_error": "the receiver answered HTTP 500",
          "last_duration_ms": 1832,
          "delivered_at": null,
          "created_at": "2026-11-14T09:00:00.000Z"
        }
      ]
    }

#What BoxLatvia sends

A POST with Content-Type: application/json. The body is always an event: an envelope with an id, a type, the time it was created and the data of that type.

HeaderMeaning
BoxLatvia-SignatureProves the message is from BoxLatvia and was not changed: t=<unix seconds>,v1=<signature>. See verifying.
BoxLatvia-EventThe event type, for example order.placed.
BoxLatvia-Event-IdThe event's id. The same for every attempt: use it to ignore duplicates.
BoxLatvia-Delivery-IdThe delivery (dlv_…), as in the delivery history.
User-AgentBoxLatvia-Webhooks/1.0

#order.placed

{
  "id": "evt_3f9c1b2a-7d4e-4c8a-9b1e-5a6d7e8f9012",
  "type": "order.placed",
  "created_at": "2026-11-14T09:12:30.412Z",
  "data": {
    "order": {
      "id": "614211b3-38be-4ba5-94e2-6f177542a174",
      "reference": "ORD-MI3K7ZQ0-4F2A",
      "status": "PAID",
      "deal_status": "AWAITING",
      "confirm_deadline": "2026-11-15T09:12:30.000Z",
      "confirmed_at": null,
      "failed_at": null,
      "box_id": "c4883b4a-4e38-47bf-8a69-ef025917e022",
      "box_external_id": "SKU-3M",
      "location_id": "9d80d5f4-d17a-4f3e-99f6-4ab43b132bc3",
      "location_external_id": "WH-IMANTA",
      "rent_from": "2026-12-01",
      "rent_to": "2027-02-28",
      "rental_units": 3,
      "unit_price": 31.5,
      "amount": 94.5,
      "currency": "EUR",
      "extra_services": [],
      "customer": {
        "name": "Jānis Ozols",
        "email": "janis.ozols@example.com",
        "phone": "+371 20000001"
      },
      "paid_at": "2026-11-14T09:12:30.000Z",
      "refunded_at": null,
      "created_at": "2026-11-14T09:10:02.000Z",
      "updated_at": "2026-11-14T09:12:30.000Z"
    }
  }
}

data.order is the same Order object that GET /v1/orders/{id} returns.

#order.cancelled

{
  "id": "evt_a41d77c0-2b5e-4f19-8c3a-90e1d2f3a4b5",
  "type": "order.cancelled",
  "created_at": "2026-11-14T11:20:00.287Z",
  "data": {
    "order": {
      "id": "5aad7dee-7f4b-4ca3-a908-b0a87b8792b6",
      "reference": "ORD-MI3M5X44-27E8",
      "status": "REFUNDED",
      "deal_status": "FAILED",
      "confirm_deadline": "2026-11-15T09:12:30.000Z",
      "confirmed_at": null,
      "failed_at": "2026-11-14T11:20:00.000Z",
      "box_id": "c4883b4a-4e38-47bf-8a69-ef025917e022",
      "box_external_id": "SKU-3M",
      "location_id": "9d80d5f4-d17a-4f3e-99f6-4ab43b132bc3",
      "location_external_id": "WH-IMANTA",
      "rent_from": "2026-12-01",
      "rent_to": "2027-02-28",
      "rental_units": 3,
      "unit_price": 31.5,
      "amount": 94.5,
      "currency": "EUR",
      "extra_services": [],
      "customer": {
        "name": "Pēteris Kalniņš",
        "email": "peteris.kalnins@example.com",
        "phone": null
      },
      "paid_at": "2026-11-14T09:50:00.000Z",
      "refunded_at": "2026-11-14T11:20:00.000Z",
      "created_at": "2026-11-14T09:48:10.000Z",
      "updated_at": "2026-11-14T11:20:00.000Z"
    }
  }
}

#box.availability_changed

{
  "id": "evt_b8e20a64-91c3-4d7f-a5b6-0c1d2e3f4a5b",
  "type": "box.availability_changed",
  "created_at": "2026-11-14T09:12:30.415Z",
  "data": {
    "box": {
      "id": "c4883b4a-4e38-47bf-8a69-ef025917e022",
      "external_id": "SKU-3M",
      "name": "Box 3 m²",
      "available_units": 5,
      "total_units": 10
    },
    "reason": "order_placed",
    "order_id": "614211b3-38be-4ba5-94e2-6f177542a174",
    "order_reference": "ORD-MI3K7ZQ0-4F2A"
  }
}

reason is order_placed or order_cancelled. The event carries the number after the change, not "minus one": if you miss an event, the next one puts you right.

#webhook.test

{
  "id": "evt_0d6c3e91-5a2b-4f84-b7c1-2e9f8a7b6c5d",
  "type": "webhook.test",
  "created_at": "2026-11-14T09:20:03.100Z",
  "data": {
    "message": "This is a test event from BoxLatvia."
  }
}

#Verify the signature

Anyone can send a request to your address, so check that it really is from BoxLatvia. Every event is signed with your webhook's secret (whsec_…):

  1. Take the t and the v1 value(s) from the BoxLatvia-Signature header. There can be two v1 while you are changing the secret.
  2. Build the text t + "." + body, where body is the request body exactly as received, byte for byte. Do not parse it and write it out again: that changes it.
  3. Compute HMAC-SHA256 of that text with your secret as the key, as lower-case hex.
  4. Compare it with each v1 using a constant-time comparison. Accept if one matches.
  5. Reject the message if t is more than 5 minutes from your clock: that stops someone replaying an old message.
Node.js
import crypto from "node:crypto";

// rawBody: the request body exactly as received (a string or Buffer), NOT parsed and re-serialised
export function verifyBoxLatviaSignature(rawBody, header, secret, toleranceSeconds = 300) {
const t = Number(/t=(\d+)/.exec(header)?.[1]);
const signatures = [...header.matchAll(/v1=([0-9a-f]+)/g)].map((m) => m[1]);
if (!t || signatures.length === 0) return false;
if (Math.abs(Date.now() / 1000 - t) > toleranceSeconds) return false; // too old: a replay?
const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
return signatures.some((s) => s.length === expected.length && crypto.timingSafeEqual(Buffer.from(s), Buffer.from(expected)));
}

// Express: app.post("/webhooks/boxlatvia", express.raw({ type: "application/json" }), (req, res) => {
//   if (!verifyBoxLatviaSignature(req.body, req.get("BoxLatvia-Signature") ?? "", process.env.BOXLATVIA_WEBHOOK_SECRET)) return res.sendStatus(401);
//   const event = JSON.parse(req.body);
//   queue.add(event);          // do the real work later ...
//   res.sendStatus(200);       // ... and answer quickly
// });
Python
import hashlib, hmac, re, time

def verify_boxlatvia_signature(raw_body: bytes, header: str, secret: str, tolerance_seconds: int = 300) -> bool:
  """raw_body: the request body exactly as received (bytes), not parsed and re-serialised."""
  t = re.search(r"t=(\d+)", header)
  signatures = re.findall(r"v1=([0-9a-f]+)", header)
  if not t or not signatures:
      return False
  if abs(time.time() - int(t.group(1))) > tolerance_seconds:  # too old: a replay?
      return False
  expected = hmac.new(secret.encode(), t.group(1).encode() + b"." + raw_body, hashlib.sha256).hexdigest()
  return any(hmac.compare_digest(s, expected) for s in signatures)

# Flask: verify_boxlatvia_signature(request.get_data(), request.headers.get("BoxLatvia-Signature", ""), SECRET)
PHP
<?php
// $rawBody: the request body exactly as received: file_get_contents('php://input')
function verifyBoxLatviaSignature(string $rawBody, string $header, string $secret, int $toleranceSeconds = 300): bool {
  if (!preg_match('/t=(\d+)/', $header, $t) || !preg_match_all('/v1=([0-9a-f]+)/', $header, $m)) return false;
  if (abs(time() - (int)$t[1]) > $toleranceSeconds) return false; // too old: a replay?
  $expected = hash_hmac('sha256', $t[1] . '.' . $rawBody, $secret);
  foreach ($m[1] as $signature) {
      if (hash_equals($expected, $signature)) return true;
  }
  return false;
}

// $ok = verifyBoxLatviaSignature(file_get_contents('php://input'), $_SERVER['HTTP_BOXLATVIA_SIGNATURE'] ?? '', getenv('BOXLATVIA_WEBHOOK_SECRET'));

#Delivery and retries

#When something was missed

Webhooks are the fast path; the API is the source of truth. After an outage, or when you start, ask for everything that changed since the last order you processed, and repeat until there is no next_cursor:

Shell
curl "$API/v1/orders?updated_since=2026-11-14T10:00:00Z" -u "$CLIENT_ID:$CLIENT_SECRET"

The same goes for stock: read the box for its current available_units. You can also send a delivery again from the history (redeliver).

#Keeping it secure