Webhooks
Tā vietā, lai API jautātu atkal un atkal, ļaujiet BoxLatvia pašam jums paziņot. Webhook ir jūsu adrese, ko BoxLatvia izsauc ar nelielu JSON ziņojumu tajā brīdī, kad ar jūsu telpām kaut kas notiek.
#Notikumi
| Notikums | Tiek sūtīts, kad | Ko saņemat |
|---|---|---|
order.placed | par vienu no jūsu telpām ir apmaksāts pasūtījums | viss pasūtījums ar nomnieka kontaktdatiem |
order.cancelled | apmaksāts pasūtījums tiek atmaksāts vai atcelts | viss pasūtījums ar jauno statusu |
box.availability_changed | telpas brīvo vienību skaits mainās pasūtījuma dēļ (samazinās, kad pasūtījums veikts, palielinās, kad atcelts) | telpa un tās jaunais brīvo vienību skaits |
webhooks:write, gan orders:read. box.availability_changed personas datus nesatur.#Ātrs sākums
-
#Pieteikšanās
Reģistrējiet savu adresi un izvēlieties notikumus. Saglabājiet atbildē saņemto
secret: tas tiek parādīts tikai vienreiz.Pieteikšanāscurl -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" } -
#Saņemšana un pārbaude
Jūsu adrese saņem
POSTar JSON saturu. Pārbaudiet parakstu un atbildiet ar2xxstatusu 10 sekunžu laikā. Īsto darbu veiciet pēc tam: ielieciet notikumu rindā un atbildiet uzreiz. -
#Testa nosūtīšana
Pārbaudiet visu ķēdi, negaidot īstu pasūtījumu.
Testa notikumscurl -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." }RezultātsPiegāžu vēsture parāda, kas notika ar katru notikumu un kāpēc mēģinājums neizdevās.
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" } ] }
#Ko BoxLatvia sūta
POST ar Content-Type: application/json. Saturs vienmēr ir notikums: aploksne ar id, type, izveides laiku un attiecīgā tipa data.
| Galvene | Nozīme |
|---|---|
BoxLatvia-Signature | Pierāda, ka ziņojums ir no BoxLatvia un nav mainīts: t=<unix sekundes>,v1=<paraksts>. Skatiet pārbaudi. |
BoxLatvia-Event | Notikuma tips, piemēram, order.placed. |
BoxLatvia-Event-Id | Notikuma id. Visiem mēģinājumiem tas pats: izmantojiet to dublikātu ignorēšanai. |
BoxLatvia-Delivery-Id | Piegāde (dlv_…), kā piegāžu vēsturē. |
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 ir tas pats pasūtījuma objekts, ko atgriež GET /v1/orders/{id}.
#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 ir order_placed vai order_cancelled. Notikums nes skaitli pēc izmaiņas, nevis "mīnus viens": ja kādu notikumu nokavējat, nākamais jūs izlabos.
#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."
}
}#Paraksta pārbaude
Jūsu adresei pieprasījumu var nosūtīt ikviens, tāpēc pārbaudiet, vai tas tiešām ir no BoxLatvia. Katrs notikums tiek parakstīts ar jūsu webhook noslēpumu (whsec_…):
- No galvenes
BoxLatvia-Signaturepaņemiettunv1vērtību(-as). Kamēr maināt noslēpumu, var būt diviv1. - Izveidojiet tekstu
t + "." + body, kurbodyir pieprasījuma saturs tieši tāds, kā saņemts, baits pa baitam. Nepārveidojiet to: parsēšana un atkārtota rakstīšana to maina. - Aprēķiniet šī teksta HMAC-SHA256 ar savu noslēpumu kā atslēgu, kā hex ar mazajiem burtiem.
- Salīdziniet to ar katru
v1, izmantojot nemainīga laika salīdzināšanu. Pieņemiet, ja kāds sakrīt. - Noraidiet ziņojumu, ja
tatšķiras no jūsu pulksteņa vairāk nekā par 5 minūtēm: tas aptur vecu ziņojumu atkārtošanu.
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'));#Piegāde un atkārtošana
- Atbildiet ar 2xx statusu 10 sekunžu laikā. Jebkas cits (cits statuss, nav atbildes, novirzīšana, savienojuma problēma) tiek uzskatīts par neveiksmi. Novirzīšanas netiek sekotas.
- Neveiksmīga piegāde tiek atkārtota pēc 1 min, 5 min, 30 min, 2 h, 6 h, 12 h, 24 h: 8 mēģinājumi aptuveni divu dienu laikā, pēc tam tā tiek atmesta (
failed). - Automātiska izslēgšana: webhook, kas neizdodas 30 mēģinājumos pēc kārtas, tiek izslēgts (
status: "disabled"), lai mēs nezvanītu uz adresi, kas vairs nepastāv. Novērsiet problēmu un iestatietstatusuzactive. Notikumi, kas notiek, kamēr tas izslēgts, netiek ierindoti: lai panāktu iepalikušo, nolasiet pasūtījumus. - Vismaz vienreiz, nevis tieši vienreiz. Viens un tas pats notikums var atnākt divreiz (piemēram, ja jūsu atbilde bija lēna). Glabājiet apstrādāto
BoxLatvia-Event-Idvērtības un ignorējiet atkārtojumus. - Secība nav garantēta. Vēlāks notikums var atnākt pirms agrāka. Izmantojiet pasūtījuma
updated_atun absolūto skaitli pieejamības notikumā, nevis ierašanās secību. - No kurienes tas nāk. Izsaukumi nāk no BoxLatvia serveriem, kuru adreses nav fiksētas, tāpēc paļaujieties uz parakstu, nevis uz sūtītāja adresi. Jūsu adresei jābūt
httpsar publisku resursdatora nosaukumu, portam 443 vai 8443; adreses, kas norāda uz privātu tīklu, tiek noraidītas.
#Ja kaut kas ir nokavēts
Webhooks ir ātrais ceļš; API ir patiesības avots. Pēc pārtraukuma vai sākot darbu pieprasiet visu, kas mainījies kopš pēdējā apstrādātā pasūtījuma, un atkārtojiet, līdz nav next_cursor:
curl "$API/v1/orders?updated_since=2026-11-14T10:00:00Z" -u "$CLIENT_ID:$CLIENT_SECRET"Tas pats attiecas uz pieejamību: nolasiet telpu, lai uzzinātu tās pašreizējo available_units. Piegādi var arī nosūtīt vēlreiz no vēstures (redeliver).
#Drošība
- Glabājiet
secretkā paroli: noslēpumu pārvaldniekā vai vides mainīgajā, nekad kodā vai žurnālos. - Nomainiet to laiku pa laikam vai uzreiz, ja tas varētu būt nopludinājis: nomainiet noslēpumu. Vecais darbojas vēl 24 stundas, un notikumi tiek parakstīti ar abiem, tāpēc pārslēdzoties nekas netiek zaudēts.
- Uztveriet nomnieka datus kā personas datus: glabājiet to, kas vajadzīgs nomai, aizsargājiet un neizmantojiet citiem mērķiem.
- Katrai sistēmai izveidojiet savu webhook un savus piekļuves datus, lai vienu varētu izslēgt, neietekmējot otru.