Webhooky

Udalosti, HMAC-SHA256 podpis, ochrana pred opakovaním a retry politika.

Webhooky sú rozšírením Doklado SAPI+ nad rámec SAPI-kompatibilného polling workflow. Slúžia na aktívne notifikovanie klienta o udalostiach, najmä o novom prijatom dokumente alebo zmene stavu odoslaného dokumentu.

Webhook nenahrádza polling. Klient musí vedieť dokumenty získať aj cez polling endpointy popísané v sekcii Prijímanie eFaktúry. Webhook má byť použitý ako akcelerátor spracovania, nie ako jediný zdroj pravdy.

Základné pravidlá:

webhook payload obsahuje iba metadáta udalosti, nie XML dokument,
XML obsah prijatého dokumentu si klient stiahne cez GET /v1/sapi/document/receive/{documentId},
prijatý dokument sa považuje za spracovaný až po úspešnom volaní acknowledge,
každý webhook request je podpísaný pomocou HMAC-SHA256,
klient musí webhooky spracúvať idempotentne podľa X-SAPI-Delivery-Id,
pri nedostupnosti klienta Doklado opakuje doručenie podľa retry politiky.

URL webhooku uveďte v žiadosti o aktiváciu SAPI+. Funkčný popis počíta so správou konfigurácie a webhook_secret cez webové rozhranie Doklado. Dostupnosť správy a testovania si potvrďte pri aktivácii; aktuálna REST API referencia neobsahuje endpoint na správu alebo test webhookov.

Prehľad doručenia webhooku

Ak klient nevráti HTTP 2xx, Doklado považuje doručenie webhooku za neúspešné a zaradí ho na opakovanie.

Hlavičky webhook requestu

Každý webhook request od Doklado obsahuje tieto HTTP hlavičky:

Hlavička	Povinné	Príklad hodnoty	Popis
`X-SAPI-Signature`	áno	`sha256=a3f9b2...`	HMAC-SHA256 podpis vypočítaný z timestampu a raw request body.
`X-SAPI-Timestamp`	áno	`1778531400`	Unix timestamp odoslania webhooku. Slúži na ochranu pred replay útokom.
`X-SAPI-Webhook-Id`	áno	`wh_01HX0000000000000000000000`	Identifikátor webhook konfigurácie v Doklado.
`X-SAPI-Delivery-Id`	áno	`del_01HX0000000000000000000000`	Unikátne ID doručenia. Pri retry toho istého eventu zostáva rovnaké.
`Content-Type`	áno	`application/json`	Formát tela webhook requestu.

Overenie podpisu

Doklado vypočíta podpis z raw request body. Klient musí použiť presné byty prijatého tela pred JSON parsovaním.

signed_payload = X-SAPI-Timestamp + "." + raw_request_body
signature = HMAC-SHA256(webhook_secret, signed_payload)
X-SAPI-Signature = "sha256=" + hex(signature)

Odporúčané overenie na strane klienta:

Skontrolovať, že X-SAPI-Timestamp nie je starší ako povolená tolerancia, odporúčane 5 minút.
Vypočítať HMAC-SHA256 nad timestamp + "." + raw_request_body.
Porovnať vypočítaný podpis s hodnotou X-SAPI-Signature pomocou constant-time porovnania.
Skontrolovať, či X-SAPI-Delivery-Id už nebol spracovaný.
Až potom spracovať payload.

Ak podpis nesedí, klient musí webhook odmietnuť odpoveďou HTTP 401 alebo HTTP 403.

Typy udalostí

Event	Trigger	Odporúčaná akcia klienta
`document.received`	Doklado prijalo nový dokument pre daný `participantId`.	Stiahnuť detail cez `GET /v1/sapi/document/receive/{documentId}` a po úspešnom spracovaní zavolať `acknowledge`.
`document.acknowledged`	Dokument bol potvrdený cez `/acknowledge`.	Zapísať stav do klientského systému, ak klient sleduje spätné potvrdenia.
`document.send.accepted`	Odoslaný dokument bol technicky prijatý Doklado na spracovanie.	Uložiť `providerDocumentId` a sledovať ďalší stav.
`document.send.delivered`	Odoslaný dokument dosiahol stav úspešného doručenia podľa dostupnej transportnej alebo stavovej odpovede.	Aktualizovať stav odoslania v klientskom systéme.
`document.send.failed`	Odoslanie alebo doručenie dokumentu zlyhalo.	Zobraziť chybu používateľovi alebo spustiť interné opravné workflow podľa typu chyby.
`webhook.ping`	Test doručenia z webového rozhrania alebo API.	Overiť podpis a vrátiť `HTTP 2xx`.
`document.reconciliation.completed`	Doklado napárovalo doklad na bankovú transakciu. Podmienka pripojeného bankového účtu v Doklado.	Aktualizovať stav dokladu v klientskom systéme a uložiť referenciu na bankovú transakciu.

Štruktúra webhook payloadu

Doklado odosiela POST na nakonfigurovaný webhook endpoint klienta.

Príklad payloadu pre document.received:

{
  "deliveryId": "del_01HX0000000000000000000000",
  "webhookId": "wh_01HX0000000000000000000000",
  "event": "document.received",
  "timestamp": "2026-05-11T12:00:05Z",
  "participantId": "0245:9876543210",
  "data": {
    "documentId": "doc_01HX0000000000000000000000",
    "clientDocumentId": "INV-2026-0001",
    "documentTypeId": "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1",
    "processId": "urn:fdc:peppol.eu:2017:poacc:billing:01:1.0",
    "senderParticipantId": "0245:1234567890",
    "receiverParticipantId": "0245:9876543210",
    "receivedAt": "2026-05-11T12:00:05Z",
    "status": "RECEIVED",
    "payloadFormat": "XML"
  }
}

Polia payloadu:

Pole	Typ	Popis
`deliveryId`	string	Identifikátor doručenia. Zhoduje sa s hlavičkou `X-SAPI-Delivery-Id`.
`webhookId`	string	Identifikátor webhook konfigurácie. Zhoduje sa s hlavičkou `X-SAPI-Webhook-Id`.
`event`	string	Typ udalosti, napr. `document.received`.
`timestamp`	datetime	Čas vzniku alebo odoslania udalosti v ISO 8601.
`participantId`	string	Peppol Participant ID, ktorého sa udalosť týka.
`data`	object	Metadáta udalosti. Pre dokumentové udalosti obsahuje najmä identifikátory dokumentu a stav.

Pre dokumentové udalosti objekt data používa rovnaké názvy polí ako DocumentMetadata, doplnené o stavové a časové polia relevantné pre daný event.

Retry politika doručenia

Webhook sa považuje za úspešne doručený, ak klient vráti akýkoľvek HTTP 2xx status do 30 sekúnd.

Ak klient neodpovie včas alebo vráti non-2xx status, Doklado opakuje doručenie:

Pokus	Oneskorenie
`1`	1 minúta
`2`	5 minút
`3`	30 minút

Po vyčerpaní retry pokusov sa konkrétne doručenie označí ako FAILED. Webhook konfigurácia sa môže automaticky deaktivovať, ak opakovane zlyháva viac udalostí za sebou. Presné limity deaktivácie sú prevádzkové nastavenie Doklado.

Bezpečné a spoľahlivé spracovanie

Toleranciu timestampu kontrolujte voči aktuálnemu času vrátane neprimerane budúcich hodnôt. Identifikátor doručenia označte ako spracovaný až po bezpečnom uložení udalosti. Pre už prijatú udalosť vráťte úspešné potvrdenie bez opakovania vedľajších účinkov.

Dlhšie spracovanie XML vykonajte po trvalom uložení webhooku, aby ste stihli odpovedať do 30 sekúnd. Pravidelný polling zachytí aj dokumenty, ktorých notifikácia sa po opakovaných pokusoch nedoručila.

Was this page helpful?