BoxLatviaIzstrādātājiem
Pieprasīt piekļuvi
Pamācības

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

NotikumsTiek sūtīts, kadKo saņemat
order.placedpar vienu no jūsu telpām ir apmaksāts pasūtījumsviss pasūtījums ar nomnieka kontaktdatiem
order.cancelledapmaksāts pasūtījums tiek atmaksāts vai atceltsviss pasūtījums ar jauno statusu
box.availability_changedtelpas 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
Piezīme
Abi pasūtījumu notikumi satur nomnieka vārdu, e-pastu un tālruni. Tie ir personas dati: izmantojiet tos tikai telpas nodošanai un nomas apkalpošanai. Lai tiem pieteiktos, vajadzīgas gan tiesības webhooks:write, gan orders:read. box.availability_changed personas datus nesatur.

#Ātrs sākums

  1. #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ās
    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. #Saņemšana un pārbaude

    Jūsu adrese saņem POST ar JSON saturu. Pārbaudiet parakstu un atbildiet ar 2xx statusu 10 sekunžu laikā. Īsto darbu veiciet pēc tam: ielieciet notikumu rindā un atbildiet uzreiz.

  3. #Testa nosūtīšana

    Pārbaudiet visu ķēdi, negaidot īstu pasūtījumu.

    Testa notikums
    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."
    }
    Rezultāts

    Piegāž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"
    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.

GalveneNozīme
BoxLatvia-SignaturePierāda, ka ziņojums ir no BoxLatvia un nav mainīts: t=<unix sekundes>,v1=<paraksts>. Skatiet pārbaudi.
BoxLatvia-EventNotikuma tips, piemēram, order.placed.
BoxLatvia-Event-IdNotikuma id. Visiem mēģinājumiem tas pats: izmantojiet to dublikātu ignorēšanai.
BoxLatvia-Delivery-IdPiegāde (dlv_…), kā piegāžu vēsturē.
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 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_…):

  1. No galvenes BoxLatvia-Signature paņemiet t un v1 vērtību(-as). Kamēr maināt noslēpumu, var būt divi v1.
  2. Izveidojiet tekstu t + "." + body, kur body ir 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.
  3. Aprēķiniet šī teksta HMAC-SHA256 ar savu noslēpumu kā atslēgu, kā hex ar mazajiem burtiem.
  4. Salīdziniet to ar katru v1, izmantojot nemainīga laika salīdzināšanu. Pieņemiet, ja kāds sakrīt.
  5. Noraidiet ziņojumu, ja t atšķiras no jūsu pulksteņa vairāk nekā par 5 minūtēm: tas aptur vecu ziņojumu atkārtošanu.
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'));

#Piegāde un atkārtošana

#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:

Shell
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