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

Události a payloady

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.removed

{
  "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. retry	~1 minuta
3. retry	~5 minut

Po 3 neúspěšných pokusech (odpověď jiná než 2xx) se doručení přeskočí.

Auto-disable

Pokud váš endpoint opakovaně selhává (více než 50 po sobě jdoucích chyb), webhook se automaticky deaktivuje. Dostanete e-mailovou notifikaci. Webhook můžete znovu aktivovat v nastavení.

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ě.