Webhooks

Áttekintés#

A Bokko webhook rendszer valós idejű HTTP értesítéseket küld, amikor egy foglalás állapota megváltozik. Így a te rendszered azonnal reagálhat az eseményekre anélkül, hogy folyamatosan lekérdeznie kellene az API-t.

• Valós idejű: az értesítés a státuszváltás pillanatában kiküldésre kerül
• HTTPS: csak biztonságos végpontra küldhető webhook
• HMAC-SHA256 aláírás: minden üzenettörzs kriptográfiailag aláírt, ellenőrizheted a hitelességét

Beállítás#

A webhook URL-t a PUT /v1/webhooks/config végponton tudod regisztrálni. Ehhez webhook.manage jogosultság szükséges.

curl -X PUT https://api.bokko.io/v1/webhooks/config \
  -H "Authorization: Bearer {API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com/webhooks/bokko" }'

URL követelmények:

• Kötelezően HTTPS protokoll
• Maximum 500 karakter hosszú
• Nem tartalmazhat hitelesítő adatokat (user:pass@)

Tiltott címtartományok:

Események#

Üzenettörzs formátum#

Minden webhook kézbesítés egy JSON objektum a következő struktúrával:

{
  "event": "booking.confirmed",
  "deliveryId": "3f2a9c0d8b7e4f1a2c3d4e5f6a7b8c9d",
  "timestamp": "2026-04-01T09:00:00.000Z",
  "salonSlug": "precision-cuts",
  "transition": {
    "id": "tr_8Kq2mZ4pX7",
    "sequence": 2,
    "occurredAt": "2026-04-01T09:15:00Z",
    "from": "requested",
    "to": "confirmed"
  },
  "booking": {
    "bookingId": "abc123",
    "publicReference": "BK-A2B3C4D5",
    "status": "confirmed",
    "locationId": "loc_belvaros_01",
    "locationSnapshot": {
      "id": "loc_belvaros_01",
      "locationSlug": "belvaros",
      "publicLocationName": "Bokko Belváros",
      "address": {
        "city": "Budapest",
        "street": "Deák Ferenc utca 1.",
        "zip": "1052"
      },
      "timezone": "Europe/Budapest"
    },
    "serviceId": "svc_haircut_01",
    "serviceName": "Hajvágás",
    "staffId": "staff_anna_01",
    "staffName": "Anna",
    "guestName": "Kiss Péter",
    "requestedSlot": {
      "date": "2026-04-05",
      "startTime": "10:00",
      "timezone": "Europe/Budapest"
    },
    "confirmedSlot": {
      "date": "2026-04-05",
      "startTime": "10:00",
      "endTime": "10:45",
      "timezone": "Europe/Budapest"
    },
    "note": null,
    "createdAt": "2026-04-01T09:00:00Z",
    "updatedAt": "2026-04-01T09:15:00Z",
    "stateVersion": 2,
    "acceptanceMode": "manual"
  }
}

A confirmedSlot a véglegesített időpontot az aktív, megerősített jellegű életciklus-állapotoknál tartalmazza, például confirmed, completed és noShow esetén. cancelled vagy declined státuszú foglalásoknál a confirmedSlot az API-ban mindig null, akkor is, ha a foglalás korábban már meg volt erősítve. A status mező alapján dől el, hogy az időpont jelenleg foglalt-e.

Sorrend, identitás és deduplikáció#

Három külön kulcs — egyik sem helyettesíti a másikat:

A timestamp és a transition.occurredAt csak tájékoztató — egy tranzakció két eseménye azonos időt hordozhat. Minden foglalási webhook állapotváltozást jelent, ezért minden esemény hordoz sequence-et. Egy megerősített foglalás két egymást követő időpont-módosítása két booking.reschedule_confirmed eseményt ad N és N+1 sequence-szel és két különböző deliveryId-val.

Automatikus elfogadás. Ha a szolgáltatás elfogadási szabálya ugyanabban a hívásban elfogadja a kérést, két esemény megy ki: booking.requested (sequence: 1, status: requested, üres confirmedSlot) és booking.confirmed (sequence: 2, acceptanceMode: automatic). Minden payload a SAJÁT eseménye állapotát írja le, nem a foglalás aktuális állapotát.

Status enum ↔ eseménynév leképezés#

A foglalás status mezője camelCase enum-ot használ (Bokko Public API konvenció), míg a webhook eseménynevei snake_case névteres formátumot (REST / event sourcing konvenció). A kettő szándékosan eltér egymástól — klienseknek az alábbi leképezést kell alkalmazni:

HTTP fejlécek#

Minden webhook kérés az alábbi egyedi fejléceket tartalmazza:

Aláírás ellenőrzés#

Node.js#

const crypto = require('crypto');

function verifySignature(rawBody, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody, 'utf8')
    .digest('hex');

  const sig = signature.replace('sha256=', '');

  return crypto.timingSafeEqual(
    Buffer.from(sig, 'hex'),
    Buffer.from(expected, 'hex')
  );
}

Python#

import hmac
import hashlib

def verify_signature(body: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(), body, hashlib.sha256
    ).hexdigest()

    sig = signature.replace('sha256=', '')

    return hmac.compare_digest(sig, expected)

Kézbesítési szabályok#

Minden kísérlet bájtra azonos törzset küld ugyanazzal a deliveryId-val és timestamp-pel. Az aláírás kísérletenként az aktuális secrettel készül, és az újraküldés az aktuálisan beállított URL-re megy — secret-rotálás után az újraküldött kézbesítést már az új secret írja alá.

Lehetséges kimenetek:

• success — 2xx válaszkód érkezett
• timeout — a végpont nem válaszolt 8 másodpercen belül
• network_error — a végpont nem volt elérhető
• http_error — nem 2xx válaszkód (pl. 500)

Kézbesítési napló#

A GET /v1/webhooks/deliveries végpont üzleti eseményenként egy rekordot ad: a kísérletek az attempts listában, a kézbesítés állapota a status mezőben (processing, retry_scheduled, succeeded, failed, exhausted). A rekordokat 12 hónapig őrizzük; egy lekérdezés legfeljebb 90 napot fedhet le.

Szűrési lehetőségek:

A lapozás cursor-alapú: a válasz meta.cursor mezőjét add meg a következő kérés cursor paraméterében.

Secret rotálás#

Ha a secreted kompromittálódott, új secretet generálhatsz:

curl -X POST https://api.bokko.io/v1/webhooks/config/rotate-secret \
  -H "Authorization: Bearer {API_KEY}"

Legjobb gyakorlatok#

1. Rendezz transition.sequence szerint, deduplikálj deliveryId szerint — lásd Sorrend, identitás és deduplikáció.
2. Dolgozz fel idempotensen, deliveryId alapján — a kézbesítés at-least-once, tehát ugyanaz az esemény újra megérkezhet (például ha a 200-as válaszod egy timeout miatt elveszett). Tárold a feldolgozott deliveryId-kat, és az ismétlést 200-zal nyugtázd újrafeldolgozás nélkül
3. Válaszolj gyorsan 200-zal, a tényleges feldolgozást aszinkron végezd — a 8 másodperces timeout szoros lehet összetett logikánál
4. Periodikusan egyeztesd a GET /v1/bookings végponttal, hogy ne maradj le eseményekről
5. Helyi fejlesztéshez használj webhook.site-ot vagy ngrok-ot a webhook fogadásához