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 polloznia 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 payload 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 capability 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#

Payload formátum#

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

<!-- doc-example: webhook-payload -->

{
  "event": "booking.confirmed",
  "deliveryId": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2026-04-01T09:00:00.000Z",
  "salonSlug": "precision-cuts",
  "booking": {
    "bookingId": "abc123",
    "publicReference": "BK-A2B3C4D5",
    "status": "confirmed",
    "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"
  }
}

A confirmedSlot a véglegesített időpontot tartalmazza, ha ilyen létezik a foglaláshoz (pl. confirmed, completed vagy noShow státuszban). cancelled vagy declined státuszú foglalásoknál ez az érték mindig null az API válaszban, még akkor is, ha a foglalás korábban meg volt erősítve. Ez azt tükrözi, hogy az időpont már nem foglalt.

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#

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égponton visszanézheted az elmúlt 90 nap kézbesítéseit.

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. Deduplikálj deliveryId alapján — bár at-most-once a garancia, hálózati anomáliák esetén érdemes ellenőrizni
2. Válaszolj gyorsan 200-zal, a tényleges feldolgozást aszinkron végezd — a 8 másodperces timeout szoros lehet összetett logikánál
3. Periodikusan egyeztesd a GET /v1/bookings végponttal, hogy ne maradj le eseményekről
4. Helyi fejlesztéshez használj webhook.site-ot vagy ngrok-ot a webhook fogadásához