Webhooks

Webhooks odesílají HTTP POST požadavky na vaši URL při každé důležité události v MujVykaz. Slouží k integraci se Zapier, Make, n8n nebo vlastními systémy.

Nastavení

1. Přejděte do Nastavení → Webhooky (nastavuje vlastník nebo administrátor) a klikněte na + Webhook.
2. V okně Nový webhook vyplňte:
   • URL — veřejná adresa s HTTPS, kam se budou odesílat požadavky
   • Popis — nepovinný, pro vaši orientaci
   • Události — vyberte, které události chcete odebírat
3. Klikněte na Vytvořit webhook.

Tajný klíč pro HMAC podpis aplikace vygeneruje sama. U webhooku v seznamu ho zobrazíte odkazem Zobrazit secret (HMAC-SHA256) a zkopírujete tlačítkem Kopírovat.

Jen HTTPS a veřejná adresa

Na adresu s http:// ani na interní adresu (localhost, privátní síť) webhook nepošleme — aplikace ji při uložení odmítne. Chrání to vás i nás před zneužitím.

Události

Aplikace umí odeslat 24 událostí a dialog Nový webhook nabízí všechny:

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.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	access_request.created, access_request.approved, access_request.rejected

Skupina Faktury se ve formuláři skryje, když má organizace vypnutou fakturaci (zbývá 20 událostí). Ukázky payloadů najdete ve Webhooks API.

HTTP hlavičky

Každý webhook požadavek obsahuje:

X-MujVykaz-Event: time_entry.created
X-MujVykaz-Signature: sha256=abc123...
X-MujVykaz-Delivery: 550e8400-e29b-41d4-a716-446655440000
Content-Type: application/json

HMAC-SHA256 ověření

Každý požadavek je podepsán vaším secret klíčem. Ověření v kódu:

Node.js

const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  const expected = 'sha256=' +
    crypto.createHmac('sha256', secret)
      .update(payload)
      .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Python

import hmac
import hashlib

def verify_signature(payload: bytes, signature: str, secret: str) -> bool:
    expected = 'sha256=' + hmac.new(
        secret.encode(), payload, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, expected)

Retry politika

• Znovu se zkouší jen chyba serveru (5xx) nebo výpadek spojení — celkem 3 pokusy (hned, po 2 s a po 10 s).
• Odpověď 3xx nebo 4xx se neopakuje: přesměrování nenásledujeme a chyba na straně klienta se opakováním nespraví.
• Po 10 neúspěšných doručeních za sebou se webhook sám vypne. Znovu ho zapnete v Nastavení → Webhooky tlačítkem Aktivovat — podrobnosti ve Webhooks API.

Napojení na Zapier, Make a n8n

Zapier

1. V Zapier vytvořte nový Zap a jako trigger zvolte "Webhooks by Zapier" → "Catch Hook".
2. Zapier vám vygeneruje URL — zkopírujte ji.
3. V Můj Výkaz jděte do Nastavení → Webhooky → + Webhook, vložte URL a vyberte události.
4. V Zapier přidejte akci (Slack zpráva, Google Sheets řádek, email...).

Make (Integromat)

1. V Make vytvořte nový scénář a přidejte modul "Webhooks" → "Custom webhook".
2. Make vám vygeneruje URL — zkopírujte ji.
3. V Můj Výkaz jděte do Nastavení → Webhooky → + Webhook, vložte URL a vyberte události.
4. Klikněte na Test — Make zachytí strukturu dat a můžete přidat další moduly.

n8n

1. V n8n přidejte node "Webhook" a nastavte HTTP Method na POST.
2. Spusťte workflow — n8n zobrazí URL. Musí být veřejná a s HTTPS (např. https://n8n.vase-firma.cz/webhook/xyz); n8n běžící jen ve vaší síti webhook nedostane.
3. V Můj Výkaz jděte do Nastavení → Webhooky → + Webhook, vložte URL a vyberte události.
4. Přidejte další n8n nody pro zpracování dat (IF podmínka, Slack, email, HTTP request...).

Test ping

U webhooku v seznamu klikněte na Test — systém odešle testovací požadavek na vaši URL a ukáže výsledek: Test prošel (odpověď 200), nebo Test selhal s důvodem („adresa neodpověděla", „odpověď 404"). Test se nepočítá do chyb doručení. U webhooku jsou ještě tlačítka Pozastavit (vypne doručování) a Aktivovat.

tip

Při vývoji použijte služby jako webhook.site nebo RequestBin pro testování bez vlastního serveru.