Webhooky

Webhooky vám doručia udalosti (faktúry, platby, sklad, Peppol doklady) na váš HTTPS endpoint. Každé doručenie je podpísané HMAC‑om a opakuje sa s exponenciálnym backoffom, kým ho nepotvrdíte HTTP 2xx. Firma s vlastným API kľúčom si endpoint registruje cez API (prvá sekcia), partner v portáli (ďalšie sekcie). Podpis, hlavičky a opakovania sú v oboch prípadoch rovnaké.

Webhooky pre firmy (vlastný API kľúč)

Endpoint zaregistrujete API kľúčom s rozsahom settings:update. Funguje od plánu Pro. Odpoveď obsahuje podpisový secret iba raz. Najviac 20 endpointov na firmu, URL musí byť https://. Rovnaké endpointy vidíte v eDoklade v Nastavenia → Webhooky. Okamžité spúšťače v Make a n8n si endpoint vytvárajú a mažú samy.

curl -X POST https://api.efaktura.sk/v1/agent/webhooks \
  -H "X-API-Key: efk_live_…" \
  -H "X-Organization-Id: <uuid>" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://erp.example.sk/efaktura","events":["peppol.document.received","invoice.paid"]}'

Udalosti faktúr nesú v data polia invoiceId, invoiceNumber, type, status, previousStatus, total (string "149.99"), currency, issueDate, dueDate, paidDate, customerName a pdfUrl. Históriu doručení vráti GET /v1/agent/webhooks/{id}/deliveries, opätovné odoslanie POST …/deliveries/{deliveryId}/redeliver, testovaciu udalosť POST /v1/agent/webhooks/{id}/test. Doručenia uchovávame 90 dní. Kompletný zoznam endpointov je v API referencii (sekcia Webhooks).

Partneri: registrácia endpointu

Endpoint zaregistrujete v portáli v sekcii Webhooky alebo cez POST /v1/partner/webhooks — to je endpoint portálu overený vaším prihlásením (session cookie), nie hlavičkou X-API-Key; s API kľúčom vráti 401 UNAUTHORIZED. Pri vytvorení dostanete podpisový secret iba raz. Uložte si ho. Jeden partner môže mať najviac 20 endpointov; URL musí byť https://. Endpoint štandardne dostáva udalosti za všetky organizácie partnera; voliteľným orgId pri vytvorení ho obmedzíte na jedinú organizáciu.

Partneri: typy udalostí

Payload udalostí participant.* nesie data.participantId (0245:DIČ, v sandboxe 9915:DIČ), data.scheme, data.mode (live / test), data.source (partner_claim / api_enroll / api_deactivate) a časovú pečiatku activatedAt / failedAt / deactivatedAt; participant.failed navyše data.code a data.message.

Payload udalostí peppol.document.fs_report_* nesie data.direction (sent / received), data.invoiceId alebo data.receivedDocumentId, data.originalDocumentId, data.state, data.issues a data.decidedAt. Aktuálny stav hlásenia je aj v poli fs_report v GET /v1/agent/peppol/status/{invoiceId} a GET /v1/agent/peppol/received/{id}.

Formát payloadu

Telo je JSON s obálkou event / timestamp (ISO 8601) / data. Pole data.orgId je vždy prítomné a identifikuje klientsku organizáciu. Pri test sendoch nesie data.mode = "test".

{
  "event": "peppol.document.delivered",
  "timestamp": "2026-06-12T19:48:01.000Z",
  "data": {
    "invoiceId": "b1f0…",
    "invoiceNumber": "2026001",
    "documentType": "invoice",
    "mode": "test",
    "state": "DELIVERED",
    "messageId": "…",
    "transactionId": "…",
    "orgId": "0a2c…"
  }
}

Hlavičky

Overenie podpisu

Podpisuje sa reťazec <timestamp>.<raw body> pomocou HMAC‑SHA256 a vášho secretu, výsledok je lowercase hex v segmente v1=. Počas rotácie secretu môže hlavička obsahovať viac segmentov v1= (starý + nový): stačí, ak sa zhoduje ktorýkoľvek. Porovnávajte v časovo‑konštantnom čase a odmietnite príliš staré timestamp (ochrana proti replayu).

import { createHmac, timingSafeEqual } from "node:crypto";

function verify(rawBody, header, secret, toleranceSec = 300) {
  const parts = Object.fromEntries(
    header.split(",").map((kv) => kv.split("="))
  );
  const t = Number(parts.t);
  if (!t || Math.abs(Date.now() / 1000 - t) > toleranceSec) return false;

  const expected = createHmac("sha256", secret)
    .update(`${t}.${rawBody}`)
    .digest("hex");

  // header may carry several v1=… segments during secret rotation
  return header
    .split(",")
    .filter((kv) => kv.startsWith("v1="))
    .some((kv) => {
      const got = kv.slice(3);
      return (
        got.length === expected.length &&
        timingSafeEqual(Buffer.from(got), Buffer.from(expected))
      );
    });
}

Doručovanie a opakovania

Doručenie je durabilné (fronta + perzistovaná história). Endpoint má odpovedať HTTP 2xx do niekoľkých sekúnd; spracovanie spravte asynchrónne. Pri zlyhaní (ne‑2xx alebo timeout) sa doručenie opakuje 10× počas približne 2,7 dňa: spolu 11 pokusov, takže endpoint, ktorý cez víkend nebeží, dostane všetky udalosti.

Po poslednom neúspešnom pokuse sa doručenie označí ako zlyhané; z portálu ho stále viete znovu odoslať (replay).

Schránka udalostí (pull)

Každá udalosť sa zapíše aj do schránky udalostí, a to aj keď nemáte zaregistrovaný žiadny endpoint. Ak webhook prijať nemôžete (firewall) alebo výpadok trval dlhšie ako opakovania, stiahnite si zmeškané udalosti cez GET /v1/agent/events partnerským kľúčom. Telo v poli payload je presne to, čo by poslal webhook.

curl "https://api.efaktura.sk/v1/agent/events?after=1841&limit=100" \
  -H "X-API-Key: efk_pk_live_…"

Testovanie

V portáli viete poslať testovací event na endpoint, pozrieť si históriu doručení (payload + odpoveď) a znovu‑odoslať (replay) ktorékoľvek minulé doručenie. V sandboxe (test kľúč) fire‑uje reálny peppol.document.delivered s data.mode = "test" po doručení medzi zaregistrovanými test účastníkmi.