Webhookok

Webhook regisztrálása

Az alkalmazásból: Webhookok oldal (admin menü) — add meg a cél-URL-t és az aláíró titkot. A titok write-only: mentés után nem olvasható vissza.

API-n keresztül, admin API-kulccsal:

curl -X POST https://app.facturifirma.ro/api/v1/webhooks \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/webhook", "secret": "<SIGNING_SECRET>"}'

Események

Jelenleg egyetlen eseménytípus kerül kiküldésre:

Idővel új eseménytípusok jönnek; kezeld az „event” mezőt bővíthetőként, és hagyd figyelmen kívül az ismeretlen típusokat.

Payload

Minden kézbesítés egy POST JSON-törzzsel:

POST https://example.com/webhook

{
  "event": "document.changed",
  "documentId": "8b1f7c02-4c33-4a6e-9f0d-2f6f6f0a9d11",
  "at": "2026-07-15T09:30:00Z"
}

Fejlécek

Minden kérés hordozza az eseménytípust és a törzs aláírását:

Content-Type: application/json
X-Facturifirma-Event: document.changed
X-Facturifirma-Signature: sha256=<hex(HMAC-SHA256(secret, body))>

Az aláírás ellenőrzése

Az aláírás a nyers kérés-törzs HMAC-SHA256-a az aláíró titkoddal, „sha256=<hex>” formátumban. Hasonlítsd össze konstans időben:

import crypto from "node:crypto";

function verify(rawBody, signatureHeader, secret) {
  const expected = "sha256=" +
    crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(signatureHeader), Buffer.from(expected));
}

Kézbesítés és újrapróbálkozás

A kézbesítések job-sorból futnak automatikus újrapróbálkozással (at-least-once, sorrendgarancia nélkül). A végpontodnak 2xx-szel kell válaszolnia; minden más hibának számít és újrapróbáljuk.