Webhooks API

Detailní reference k webhook systému MujVykaz — události, payloady, hlavičky a ověření.

HTTP hlavičky

Každý webhook požadavek obsahuje tyto hlavičky:

Hlavička	Popis	Příklad
X-MujVykaz-Event	Název události	time_entry.created
X-MujVykaz-Signature	HMAC-SHA256 podpis	sha256=a1b2c3...
X-MujVykaz-Delivery	Unikátní ID doručení (UUID)	550e8400-e29b-...
Content-Type	Formát těla	application/json

Dostupné události

Aplikace umí odeslat těchto 28 událostí.

Skupina	Události
Výkazy	time_entry.created, time_entry.updated, time_entry.deleted, time_entry.submitted, time_entry.approved, time_entry.invoiced
Faktury	invoice.created, invoice.sent, invoice.paid, invoice.cancelled
Náklady	expense.created, expense.updated, expense.deleted, expense.approved, expense.invoiced
Úkoly	task.created, task.updated, task.completed, task.deleted
Tým	user.created, user.invited
Projekty	project.created, project.updated
Klienti	client.created, client.updated
Žádosti o přístup ke klientovi	access_request.created, access_request.approved, access_request.rejected

Komentáře webhook nemají záměrně — jejich text je citlivá komunikace a posílat ho do cizího systému nechceme.

Formulář nabízí jen část událostí

Dialog Nový webhook (Nastavení → Integrace → Webhooks) dnes nabízí 15 událostí v pěti skupinách: Výkazy, Faktury, Tým, Projekty, Klienti. Skupina Faktury se navíc skryje, když má organizace vypnutou fakturaci — pak zbývá 11 událostí ve čtyřech skupinách.

Zaškrtnout ve formuláři nejde zbylých 13 událostí: time_entry.invoiced, celé skupiny Náklady, Úkoly a Žádosti o přístup ke klientovi. Odeslat je aplikace umí, jen se k nim v dialogu neproklikáte. Pokud je potřebujete, napište nám.

Události a payloady

Níže jsou ukázky těla požadavku u nejčastějších událostí.

time_entry.created

{
  "event": "time_entry.created",
  "timestamp": "2026-03-27T10:30:00Z",
  "data": {
    "id": 123,
    "user_id": 5,
    "project_id": 10,
    "date": "2026-03-27",
    "hours": 2.5,
    "description": "Implementace API",
    "status": "draft",
    "billable": true
  }
}

time_entry.approved

{
  "event": "time_entry.approved",
  "timestamp": "2026-03-27T14:00:00Z",
  "data": {
    "id": 123,
    "status": "approved",
    "approved_by": 2,
    "approved_at": "2026-03-27T14:00:00Z"
  }
}

invoice.created

{
  "event": "invoice.created",
  "timestamp": "2026-03-27T15:00:00Z",
  "data": {
    "id": 45,
    "client_id": 3,
    "number": "2026003",
    "total": 46350.00,
    "currency": "CZK",
    "issued_at": "2026-03-27",
    "due_at": "2026-04-10"
  }
}

user.created / user.invited

{
  "event": "user.created",
  "timestamp": "2026-03-27T09:00:00Z",
  "data": {
    "id": 15,
    "name": "Jan Novák",
    "email": "jan@firma.cz",
    "role": "worker"
  }
}

project.created / project.updated

{
  "event": "project.created",
  "timestamp": "2026-03-27T08:00:00Z",
  "data": {
    "id": 10,
    "name": "Nový web",
    "client_id": 3,
    "hourly_rate": 1500,
    "billable": true
  }
}

HMAC ověření

Podpis se počítá z celého těla požadavku (raw body) pomocí vašeho secret klíče:

HMAC-SHA256(secret, raw_body) → hex digest → "sha256=" + digest

Vždy používejte timing-safe porovnání (viz Webhooks nastavení).

Retry politika

Pokus	Čekání
1. (původní)	Okamžitě
2. pokus	~2 sekundy
3. pokus	~10 sekund

Opakuje se jen to, co se může samo spravit: chyba serveru (5xx) nebo výpadek spojení. Odpověď 3xx nebo 4xx se neopakuje — přesměrování nenásledujeme a chyba na straně klienta se opakováním nespraví. Po třetím neúspěšném pokusu se doručení vzdáme.

Auto-disable

Pokud váš endpoint opakovaně selhává, webhook se po 10 po sobě jdoucích neúspěšných doručeních automaticky deaktivuje. Jediné úspěšné doručení počítadlo vynuluje.

Aplikace vás na to sama neupozorní — nepřijde e-mail ani zpráva v aplikaci. Počet chyb i to, jestli je webhook aktivní, uvidíte v Nastavení → Integrace → Webhooks; deaktivovaný webhook tam znovu zapnete tlačítkem Aktivovat. Když je pro vás doručování kritické, hlídejte si stav na své straně.

tip

Endpoint by měl odpovědět do 5 sekund. Pokud zpracování trvá déle, přijměte webhook (odpovězte 200) a zpracujte ho asynchronně.

Hromadné operace (bulk) a webhooky

Při hromadném schválení nebo odeslání výkazů (bulk-status) jsou webhooky odesílány efektivně v dávkách s omezeným souběhem — ne synchronně jeden po druhém. To znamená:

• Vaše aplikace může přijmout webhooky prakticky současně (paralelně, limit 10 souběžných)
• Pořadí příjmu není garantováno (záleží na latenci sítě)
• Každý výkaz v dávce generuje samostatný webhook event

Doporučujeme navrhovat endpoint jako idempotentní — bezpečné opakování zpracování stejného eventu.