Webhooks

En webhook er en adresse hos et annet system som får beskjed når noe skjer, for eksempel når en ordre er klar. Hver beskjed er en POST med hele objektet slik det var da.

Verkstedet legger inn adressen

Verkstedet legger inn en adresse (https) og velger hva den skal få beskjed om. Du gir verkstedet adressen, og verkstedet gir deg hemmeligheten.

Et verksted kan ha 10 adresser i bruk. Alle hendelsene står i katalogen over hendelser.

Beskjeden

Hver beskjed er en POST med JSON, og disse overskriftene:

POST /din-adresse HTTP/1.1
Content-Type: application/json
User-Agent: vbeslag-webhooks/1
Vbeslag-Event-Id: evt_01JEX4Q7R2M9T5V8W0Y3Z6A1B4
Vbeslag-Event-Type: order.ready
Vbeslag-Delivery-Attempt: 1
Vbeslag-Signature: t=1797590527,v1=5f2b…c9e1

{
  "id": "evt_01JEX4Q7R2M9T5V8W0Y3Z6A1B4",
  "type": "order.ready",
  "apiVersion": "v1",
  "createdAt": "2026-12-14T10:42:07Z",
  "livemode": true,
  "data": {
    "order": { "number": 4711, "numberDisplay": "004711", "status": "klar", "version": 5, … },
    "change": { "from": "i_arbeid", "to": "klar" }
  }
}

• data har hele objektet slik det var da hendelsen ble sendt, for eksempel order, agreement, invoice eller customer. change er med når en ordre har flyttet status.
• livemode er false for testordre og testadresser.
• En beskjed er under 256 KB.

Sjekk signaturen

Vbeslag-Signature er t=<unix-tid>,v1=<hex HMAC-SHA256 av "t.rå-body" med hemmeligheten>. Avvis beskjeder som er eldre enn 5 minutter. Når verkstedet bytter hemmelighet, kommer to v1 i 24 timer: godta den som stemmer.

Sjekk signaturen mot den rå teksten, før du gjør den om til JSON: en omformatert body gir en annen signatur.

import crypto from 'node:crypto'
 
export function verifyVbeslag(rawBody, header, secret, toleranceSec = 300) {
  const parts = header.split(',').map((p) => p.trim().split('='))
  const t = Number(parts.find(([k]) => k === 't')?.[1])
  if (!t || Math.abs(Date.now() / 1000 - t) > toleranceSec) return false
  const expected = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex')
  return parts.some(([k, v]) => k === 'v1' && v.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(v), Buffer.from(expected)))
}

function vbeslag_verify(string $rawBody, string $header, string $secret, int $tolerance = 300): bool {
    $t = 0; $sigs = [];
    foreach (explode(',', $header) as $part) {
        [$k, $v] = array_pad(explode('=', trim($part), 2), 2, '');
        if ($k === 't') { $t = (int) $v; }
        if ($k === 'v1') { $sigs[] = $v; }
    }
    if ($t === 0 || abs(time() - $t) > $tolerance) { return false; }
    $expected = hash_hmac('sha256', $t . '.' . $rawBody, $secret);
    foreach ($sigs as $s) { if (hash_equals($expected, $s)) { return true; } }
    return false;
}

Stemmer ikke signaturen, eller er beskjeden for gammel, gjør du ingenting med den.

Svar, nye forsøk og avslåtte adresser

Svar med en 2xx innen 10 sekunder. Ellers prøver vi igjen i omtrent 45 timer, med lengre pauser for hver gang. Vbeslag-Delivery-Attempt sier hvilket forsøk det er.

• 410 Gone slår adressen av med en gang.
• 50 feil på rad gjør det samme, og verkstedet får beskjed.
• Vi følger aldri en omdirigering, og vi sender bare til offentlige adresser.

En adresse som er slått av, slår verkstedet på igjen med «Slå på igjen» under Koblinger (API).

Gikk du glipp av noe?

GET /events gir de samme beskjedene 30 dager tilbake, eldste først etter den siste id-en du har.

curl "https://vbeslag.com/api/v1/events?after=evt_01JEX4Q7R2M9T5V8W0Y3Z6A1B4&types=order.ready" \
  -H "Authorization: Bearer $VBESLAG_KEY"

Ta vare på id-en til den siste beskjeden du har behandlet, og send den som after.

Videre