Webhooky

Webhook je adresa ve vašem systému, kterou DameDoklad zavolá, když se něco stane: třeba když vystavíte fakturu nebo přijde platba. Nemusíte se tak pořád ptát API, co je nového.

Webhooky spravujete v Nastavení > Webhooky nebo přes API. K založení potřebujete tarif s webhooky, viz ceník.

Založení adresy

curl https://api.damedoklad.cz/v1/webhooks \
  -H "Authorization: Bearer $DAMEDOKLAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com/hooks/damedoklad", "events": ["invoice.issued", "received_invoice.*"] }'

Odpověď obsahuje podpisové tajemství secret, které začíná whsec_. Uvidíte ho jen jednou. Když ho ztratíte, vyměňte ho přes POST /v1/webhooks/{id}/rotate-secret; staré tajemství okamžitě přestane platit.

V events uveďte názvy událostí, předponu jako invoice.* nebo * pro všechno. Adresa musí být veřejná: soukromé a místní adresy DameDoklad odmítne a před každým doručením to ověřuje znovu.

Co přijde

Každé doručení je POST s tělem v JSON:

{
  "id": "evt_6f1c2a9b04d3e8f17a5c0b21",
  "type": "invoice.issued",
  "createdAt": "2026-10-30T09:12:44.120Z",
  "workspaceId": "wsp_…",
  "data": { "row": { "id": "inv_…", "number": "FV2026001", "status": "issued" }, "lines": [] }
}

Spolu s tím přijdou tyto hlavičky:

Kontrola podpisu

Hlavička s podpisem vypadá jako t=1793351564,v1=5f8a…. t je čas odeslání v unixových sekundách a v1 je šestnáctkové HMAC SHA-256 textu {t}.{syrové tělo} s vaším tajemstvím jako klíčem. Porovnávejte nad syrovými bajty těla, ještě před zpracováním JSON.

import { createHmac, timingSafeEqual } from 'node:crypto';

export function verify(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(',').map((part) => part.split('=')));
  const expected = createHmac('sha256', secret).update(`${parts.t}.${rawBody}`).digest('hex');
  const same = expected.length === parts.v1.length && timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
  const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) < 300;
  return same && fresh;
}

import hashlib, hmac, time

def verify(raw_body: bytes, header: str, secret: str) -> bool:
    parts = dict(part.split("=", 1) for part in header.split(","))
    signed = parts["t"].encode() + b"." + raw_body
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts["v1"]) and abs(time.time() - int(parts["t"])) < 300

Pětiminutové okno je naše doporučení proti přehrání zprávy. DameDoklad podepisuje každý pokus s novým t.

Opakování

Jakákoli odpověď 2xx do 15 sekund znamená doručeno. Všechno ostatní se opakuje, celkem nejvýš osmkrát:

Po osmém neúspěchu zůstane doručení v záznamu jako failed a můžete ho poslat znovu přes POST /v1/webhook-deliveries/{id}/retry. Záznam najdete přes GET /v1/webhooks/{id}/deliveries.

POST /v1/webhooks/{id}/test hned pošle podepsanou událost webhook.test a vrátí výsledek. Testovací události se neopakují.

Příjem událostí

• Odpovídejte rychle. Událost si uložte a zpracujte ji až potom.
• Počítejte s opakováním. Stejná událost může přijít víckrát, proto si evidujte id.
• Nespoléhejte na pořadí. V případě pochybností si načtěte aktuální stav objektu přes API.
• Událost odchází až po potvrzení transakce, takže stornovaná operace se nikdy neohlásí.

Události

Správa přes API

Webhooky spravujete těmito operacemi:

• Ask the shop to send a notification here when an order is created or changes, so an order arrives within a minute and not at the next 15-minute read. Turn it on with webhooksEnabled POST /v1/shop-connections/{id}/register-webhooks
• Send a failed delivery again POST /v1/webhook-deliveries/{id}/retry
• List the event types a webhook can subscribe to. Payloads are in the `webhooks` section of /openapi.json GET /v1/webhook-events
• List webhook endpoints GET /v1/webhooks
• Create a webhook endpoint. The signing secret is returned once. POST /v1/webhooks
• Get a webhook endpoint GET /v1/webhooks/{id}
• Update a webhook endpoint: URL, events, or pause it PATCH /v1/webhooks/{id}
• Delete a webhook endpoint and its delivery log DELETE /v1/webhooks/{id}
• List delivery attempts of a webhook endpoint, newest first GET /v1/webhooks/{id}/deliveries
• Replace the signing secret. The new secret is returned once; the old one stops working immediately. POST /v1/webhooks/{id}/rotate-secret
• Send a signed test event to this endpoint now and return the result. Test events are not retried. POST /v1/webhooks/{id}/test