Podpis odchozích požadavků

Na dvou místech volá mWork365 vás: doručuje webhooky a spouští vlastní akční tlačítka. Vaše URL je v obou případech veřejně dostupná, takže by na ni mohl zavolat kdokoli.

Proto je každý odchozí požadavek podepsaný — a to stejným mechanismem u webhooků i u tlačítek. Z podpisu ověříte, že požadavek opravdu poslal mWork365 a že se cestou nezměnil.

Podpisový klíč

Klíč zadáváte do pole Signature secret u konkrétního webhooku nebo tlačítka v Nastavení firmy → Integrace. Když ho necháte prázdný, vygenerujeme ho za vás.

Každý webhook a každé tlačítko má vlastní klíč — kompromitovaný klíč tak stačí změnit na jednom místě, aniž by to ovlivnilo ostatní integrace.

Upozornění

Signature secret je svým významem heslo. Nesdílejte ho, neukládejte do veřejných repozitářů ani do klientských aplikací.

Jak podpis vzniká

mWork365 spočítá HMAC SHA-256 z podepisovaných dat pomocí Signature secretu a výsledek pošle jako hexadecimální řetězec v hlavičce X-Provider-Signature.

Co se podepisuje, závisí na tom, odkud volání jde:

Volání	Podepisují se	Další hlavičky
Webhook (vždy POST)	celé tělo požadavku (JSON)	X-Provider-Event-Id
Tlačítko s metodou POST nebo PUT	celé tělo požadavku (JSON)	—
Tlačítko s metodou GET nebo DELETE	zřetězení metoda + URL + časové razítko	X-Timestamp s razítkem v ISO 8601 (UTC)

U tlačítek s metodou GET a DELETE se podepisuje URL tak, jak je nastavená (po dosazení značek {id} a {externalId}) — tedy bez připojených parametrů dotazu. Podpis pro GET na https://vase-sluzba.cz/sync s razítkem 2026-08-16T09:12:44.1234567Z se počítá z řetězce:

GEThttps://vase-sluzba.cz/sync2026-08-16T09:12:44.1234567Z

Ověření na vaší straně

1. Ze stejného Signature secretu a odpovídajících dat spočítejte HMAC‑SHA256.
2. Výsledek porovnejte s hodnotou v hlavičce X-Provider-Signature (porovnávejte bez ohledu na velikost písmen).
3. Pokud se neshodují, požadavek odmítněte.

Podepisuje se přesně to tělo, které dorazilo — počítejte podpis ze syrových dat požadavku, ne z JSONu, který jste si mezitím rozparsovali a znovu serializovali. Jiné pořadí polí nebo jiné mezery dají jiný podpis.

Tip

U tlačítek s metodou GET a DELETE navíc porovnejte X-Timestamp s aktuálním časem a příliš stará razítka odmítejte — zabráníte tím opakovanému přehrání zachyceného požadavku.

Ověřování podpisu je nepovinný bezpečnostní mechanismus: pokud podpis neověřujete, webhooky i tlačítka fungují stejně. Doporučujeme ho ale zapnout — bez něj nemáte jak odlišit volání z mWork365 od cizího.