Webhookok

A webhook egy HTTP POST a saját szerveredre, amikor a szervezetben valami történik: rendelés státusza változik, készlet mozog, árajánlatot elfogadnak. A webhookokat a szervezet felületén (Integrációk › Webhookok és API) vagy a webhook modul API-ján kezeled.

Elérhető események

GET https://acme.app.vecton.hu/api/webhook/events
Authorization: Bearer <token>

A válasz a szervezetnél elérhető eseménytípusok listája, típusonként a modullal (service), a kulccsal (event_key), a leírással és a payload mezőivel (payload_schema). Mindig ebből a listából dolgozz — csak a bekapcsolt modulok eseményei jelennek meg. Néhány példa:

Modul	Példák
webshop	order.status_changed, quote.sent, quote.accepted, quote.rejected, quote.converted, integration.sync_failed, currency.rate_updated
warehouse	warehouse.inventory.received, warehouse.inventory.moved, warehouse.inventory.adjusted, warehouse.procurement.received, warehouse.supplier_product.price_changed, warehouse.statistics.daily
crm	company.created, company.updated, blog_post.created, sms.delivered, sms.failed, chat.message.sent
email	email_template.created, email_template.updated, email_template.deleted

Feliratkozás

POST https://acme.app.vecton.hu/api/webhook/webhooks
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "Rendelésszinkron az ERP-be",
  "url": "https://erp.example.com/vecton/webhook",
  "events": ["order.status_changed", "quote.accepted"],
  "webshop_id": null,
  "is_active": true
}

• A válasz (201) egyszer tartalmazza az aláíró titkot (secret) — tárold el biztonságosan.
• webshop_id megadásával a webhook csak annak a webshopnak az eseményeit kapja.
• A cím nyilvános interneten elérhető kell legyen (http vagy https, a 80, 443, 8080 vagy 8443 porton). Belső és privát címre a Vecton nem kézbesít. Átirányítást a kézbesítés nem követ.
• Jog: tenant.<szervezet>.webhook.webhooks.create.

Végpont	Mire való
GET /api/webhook/webhooks	a webhookok listája
GET /api/webhook/webhooks/{id}	egy webhook
PUT /api/webhook/webhooks/{id}	módosítás
DELETE /api/webhook/webhooks/{id}	törlés
POST /api/webhook/webhooks/{id}/test	próba-kézbesítés (percenként legfeljebb 5)
POST /api/webhook/webhooks/{id}/rotate-secret	új titok; a régi azonnal érvénytelen
POST /api/webhook/webhooks/{id}/re-enable	az automatikusan kikapcsolt webhook visszakapcsolása
GET /api/webhook/webhooks/{id}/deliveries	a kézbesítési napló
GET /api/webhook/webhooks/{id}/deliveries/stats	kézbesítési statisztika
POST /api/webhook/webhooks/{id}/deliveries/{deliveryId}/retry	egy kézbesítés kézi újraküldése

A kézbesítés

POST /vecton/webhook HTTP/1.1
Content-Type: application/json
User-Agent: Vecton-Webhook/1.0
X-Webhook-Event: order.status_changed
X-Webhook-Id: <kézbesítés-azonosító>
X-Webhook-Timestamp: 1761818400
X-Webhook-Signature: t=1761818400,v1=5f2b…c9a1

{
  "event": "order.status_changed",
  "service": "webshop",
  "event_id": "…",
  "timestamp": 1761818400,
  "data": { … }
}

Mező / fejléc	Jelentés
event, X-Webhook-Event	az eseménytípus
data	az esemény adatai, a payload_schema szerint
event_id	az esemény stabil azonosítója — erre deduplikálj
X-Webhook-Id	a kézbesítés azonosítója; újrapróbáláskor ugyanaz
X-Webhook-Signature	t=<unix idő>,v1=<HMAC-SHA256 hex>

Aláírás ellenőrzése

Az aláírt szöveg "<t>.<nyers törzs>", a kulcs a webhook titka, az algoritmus HMAC-SHA256 (hex). A törzset nyersen, újrakódolás nélkül használd.

import crypto from 'node:crypto'

export function verifyVecton(rawBody, header, secret, toleranceSec = 300) {
  const parts = Object.fromEntries(header.split(',').map(p => p.split('=', 2)))
  const t = Number(parts.t)
  if (!t || !parts.v1) return false
  const expected = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex')
  const ok = expected.length === parts.v1.length
    && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1))
  return ok && Math.abs(Date.now() / 1000 - t) <= toleranceSec
}

function verify_vecton(string $rawBody, string $header, string $secret, int $tolerance = 300): bool
{
    parse_str(str_replace(',', '&', $header), $parts);
    if (empty($parts['t']) || empty($parts['v1'])) {
        return false;
    }
    $expected = hash_hmac('sha256', $parts['t'].'.'.$rawBody, $secret);

    return hash_equals($expected, $parts['v1']) && abs(time() - (int) $parts['t']) <= $tolerance;
}

Az időbélyeg-tűrés (5 perc) a visszajátszás ellen véd.

Válasz, újrapróbálás, kikapcsolás

• Siker: bármely 2xx válasz. Válaszolj gyorsan (a kapcsolódási idő korlátja 10, a teljes kérésé 30 másodperc), és a feldolgozást végezd a válasz után, saját sorban.
• Újrapróbálás: nem 2xx válasznál, időtúllépésnél vagy kapcsolódási hibánál a Vecton legfeljebb 5-ször próbálkozik, egyre ritkábban: 1 perc, 5 perc, 30 perc, 2 óra, 24 óra után.
• Kikapcsolás: 15 egymást követő sikertelen kézbesítés után a webhook automatikusan kikapcsol. A hiba javítása után a re-enable végponttal vagy a felületen kapcsold vissza.
• Sorrend és ismétlés: a kézbesítések sorrendje nem garantált, és ugyanaz az esemény ritkán kétszer is megérkezhet. Az event_id alapján deduplikálj, és a data állapotára építs, ne az érkezés sorrendjére.
• A kézbesítési napló 30 napig (a sikerteleneké 90 napig) visszakereshető.

Verziózott események

Egyes eseménytípusok egy verziózott eseményszerződésre épülnek — ilyenkor a data alakja szerződés szerint stabil. Lásd: Eseményszerződések.