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
| Event | Sent when | What you get |
|---|---|---|
order.placed | an order for one of your boxes is paid | the whole order, with the renter's contact details |
order.cancelled | a paid order is refunded or cancelled | the whole order, now with its new status |
box.availability_changed | the 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 |
orders:read as well as webhooks:write. box.availability_changed has no personal data.#Quick start
-
#Subscribe
Register your address and choose the events. Store the
secretfrom the answer: it is shown only once.Subscribecurl -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" }'const API = "https://api.boxlatvia.lv"; const auth = "Basic " + btoa(`${CLIENT_ID}:${CLIENT_SECRET}`); const res = await fetch(`${API}/v1/webhooks`, { method: "POST", headers: { Authorization: auth, "Content-Type": "application/json" }, body: JSON.stringify({ "url": "https://erp.imantastorage.example/webhooks/boxlatvia", "events": [ "order.placed", "order.cancelled", "box.availability_changed" ], "description": "Imanta ERP" }), }); console.log(res.status, await res.json());import requests API = "https://api.boxlatvia.lv" r = requests.post( f"{API}/v1/webhooks", auth=(CLIENT_ID, CLIENT_SECRET), json={ "url": "https://erp.imantastorage.example/webhooks/boxlatvia", "events": [ "order.placed", "order.cancelled", "box.availability_changed", ], "description": "Imanta ERP", }, ) print(r.status_code, r.json())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" } -
#Receive and verify
Your address receives a
POSTwith a JSON body. Verify the signature, then answer with a2xxstatus within 10 seconds. Do the real work afterwards: put the event in a queue and answer at once. -
#Send a test
Check the whole chain without waiting for a real order.
A test eventcurl -X POST "$API/v1/webhooks/cb3cf942-3e09-4b76-9b89-0143c09a8ae9/test" \ -u "$CLIENT_ID:$CLIENT_SECRET"const API = "https://api.boxlatvia.lv"; const auth = "Basic " + btoa(`${CLIENT_ID}:${CLIENT_SECRET}`); const res = await fetch(`${API}/v1/webhooks/cb3cf942-3e09-4b76-9b89-0143c09a8ae9/test`, { method: "POST", headers: { Authorization: auth }, }); console.log(res.status, await res.json());import requests API = "https://api.boxlatvia.lv" r = requests.post( f"{API}/v1/webhooks/cb3cf942-3e09-4b76-9b89-0143c09a8ae9/test", auth=(CLIENT_ID, CLIENT_SECRET), ) print(r.status_code, r.json())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 resultThe 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"const API = "https://api.boxlatvia.lv"; const auth = "Basic " + btoa(`${CLIENT_ID}:${CLIENT_SECRET}`); const res = await fetch(`${API}/v1/webhooks/cb3cf942-3e09-4b76-9b89-0143c09a8ae9/deliveries?limit=10`, { headers: { Authorization: auth }, }); console.log(res.status, await res.json());import requests API = "https://api.boxlatvia.lv" r = requests.get( f"{API}/v1/webhooks/cb3cf942-3e09-4b76-9b89-0143c09a8ae9/deliveries?limit=10", auth=(CLIENT_ID, CLIENT_SECRET), ) print(r.status_code, r.json())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.
| Header | Meaning |
|---|---|
BoxLatvia-Signature | Proves the message is from BoxLatvia and was not changed: t=<unix seconds>,v1=<signature>. See verifying. |
BoxLatvia-Event | The event type, for example order.placed. |
BoxLatvia-Event-Id | The event's id. The same for every attempt: use it to ignore duplicates. |
BoxLatvia-Delivery-Id | The delivery (dlv_…), as in the delivery history. |
User-Agent | BoxLatvia-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_…):
- Take the
tand thev1value(s) from theBoxLatvia-Signatureheader. There can be twov1while you are changing the secret. - Build the text
t + "." + body, wherebodyis the request body exactly as received, byte for byte. Do not parse it and write it out again: that changes it. - Compute HMAC-SHA256 of that text with your secret as the key, as lower-case hex.
- Compare it with each
v1using a constant-time comparison. Accept if one matches. - Reject the message if
tis more than 5 minutes from your clock: that stops someone replaying an old message.
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
// });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
// $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
- Answer with a 2xx status within 10 seconds. Anything else (another status, no answer, a redirect, a connection problem) counts as a failure. Redirects are not followed.
- A failed delivery is retried after 1 min, 5 min, 30 min, 2 h, 6 h, 12 h, 24 h: 8 attempts over about two days, then it is given up (
failed). - Switched off automatically: a webhook that fails 30 attempts in a row is switched off (
status: "disabled"), so we do not keep calling an address that is gone. Fix the problem and setstatustoactive. Events that happen while it is off are not queued: list the orders to catch up. - At least once, not exactly once. The same event can arrive twice (for example when your answer was slow). Keep the
BoxLatvia-Event-Idvalues you have handled and ignore repeats. - Order is not guaranteed. A later event can arrive before an earlier one. Use
updated_atof the order and the absolute number in the availability event, not the order of arrival. - Where it comes from. The calls come from BoxLatvia's servers whose addresses are not fixed, so rely on the signature, not on the sender's address. Your address must be
httpswith a public host name, port 443 or 8443; addresses that point inside a private network are refused.
#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:
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
- Keep the
secretlike a password: in a secrets manager or an environment variable, never in code or logs. - Replace it now and then, or at once if it may have leaked: rotate the secret. The old one keeps working for 24 hours and events are signed with both, so nothing is lost while you switch.
- Treat the renter's details as personal data: keep what you need for the rental, protect it, and do not use it for anything else.
- Give each system its own webhook and its own credentials, so one can be switched off without the other.