Dokumentacja

Webhooki

Otrzymuj podpisane powiadomienia HTTP w swoich systemach za każdym razem, gdy dokument zmienia się w facturifirma.ro.

Rejestracja webhooka

Z aplikacji: strona Webhooki (menu administracyjne) — dodaj docelowy URL i sekret podpisu. Sekret jest write-only: po zapisaniu nie można go odczytać.

Przez API, z administracyjnym kluczem API:

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>"}'

Zdarzenia

Obecnie wysyłany jest jeden typ zdarzenia:

document.changed

każda zmiana dokumentu — utworzenie, edycja, wystawienie, płatność, korekta, anulowanie lub usunięcie, dla każdego typu dokumentu (faktura, proforma, paragon, WZ, zamówienie, korekta).

Z czasem pojawią się nowe typy zdarzeń; traktuj pole „event” jako rozszerzalne i ignoruj nieznane typy.

Payload

Każda dostawa to POST z ciałem JSON:

POST https://example.com/webhook

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

Nagłówki

Każde żądanie niesie typ zdarzenia i podpis ciała:

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

Weryfikacja podpisu

Podpis to HMAC-SHA256 surowego ciała żądania z Twoim sekretem, w formacie „sha256=<hex>”. Porównuj go w stałym czasie:

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));
}

Dostarczanie i ponowienia

Dostawy wychodzą z kolejki zadań z automatycznymi ponowieniami (at-least-once, bez gwarancji kolejności). Twój endpoint musi odpowiedzieć 2xx; wszystko inne liczy się jako błąd i jest ponawiane.

Bezpieczeństwo

Akceptowane są wyłącznie absolutne URL-e http(s) rozwiązujące się na adresy publiczne (ochrona SSRF). Sekret podpisu jest szyfrowany at-rest i nigdy nie jest zwracany przez API.