Příručka
Webhooky
Upozornění na změny bez neustálého dotazování.
Webhook pošle na vaši adresu HTTPS požadavek POST, když nastane vybraná událost. Nemusíte se tak neustále dotazovat na změny. Webhook přidáte v aplikaci v Nastavení → API klíče: zadejte adresu, vyberte události a uložte si podpisový klíč. Začíná whsec_ a zobrazí se jen jednou.
| Událost | Kdy nastane | Objekt |
|---|---|---|
invoice.created | Doklad vytvořen | invoice |
invoice.updated | Doklad upraven | invoice |
invoice.issued | Doklad vystaven | invoice |
invoice.deleted | Doklad smazán | invoice |
payment.recorded | Platba zaznamenána | invoice |
payment.reversed | Úhrada zrušena | invoice |
contact.saved | Kontakt uložen | contact |
contact.deleted | Kontakt smazán | contact |
expense.saved | Výdaj uložen | expense |
expense.paid | Výdaj zaplacen | expense |
expense.deleted | Výdaj smazán | expense |
export.ready | Export připraven | export |
export.failed | Export se nepodařil | export |
Požadavek
Tělo nese jen typ události a odkaz na záznam. Aktuální stav načtěte z data.url svým API klíčem.
Content-Type: application/json
User-Agent: Fakturanet-Webhooks/1.0
Fakturanet-Event: invoice.issued
Fakturanet-Delivery: evt_6f1c2a9b0d3e4f5a6b7c8d9e
Fakturanet-Signature: t=1763457300,v1=ecadd13f6122c0abe2c0c4c7246becc7736e6f94bb9531d668aa047269a4a12d
{"id":"evt_6f1c2a9b0d3e4f5a6b7c8d9e","type":"invoice.issued","created_at":"2026-11-18T10:15:00+01:00","data":{"object":"invoice","id":123,"url":"https://api.fakturanet.cz/v1/invoices/123"}}
Pro kontrolu vaší implementace: tento příklad je podepsaný klíčem whsec_0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef v čase t=1763457300.
Ověření podpisu
Fakturanet-Signature obsahuje čas odeslání t (Unix) a v1, HMAC-SHA256 řetězce t.tělo s vaším podpisovým klíčem. Porovnejte ho v konstantním čase a odmítněte požadavky starší než 5 minut:
<?php
declare(strict_types=1);
$secret = getenv('FAKTURANET_WEBHOOK_SECRET');
$body = file_get_contents('php://input');
$header = $_SERVER['HTTP_FAKTURANET_SIGNATURE'] ?? '';
if (!preg_match('/^t=(\d+),v1=([a-f0-9]{64})$/', $header, $m)
|| abs(time() - (int) $m[1]) > 300
|| !hash_equals(hash_hmac('sha256', $m[1] . '.' . $body, $secret), $m[2])) {
http_response_code(400);
exit;
}
$event = json_decode($body, true, 512, JSON_THROW_ON_ERROR);
file_put_contents(__DIR__ . '/fakturanet-events.log', $event['id'] . ' ' . $event['type'] . PHP_EOL, FILE_APPEND | LOCK_EX);
http_response_code(204);
Doručení
- Odpovězte stavem 2xx do 10 sekund. Přesměrování se nesleduje. Webhooky odesílá úloha na pozadí, která běží každou minutu.
- Nepovedené doručení se opakuje až 10krát, s rostoucí pauzou od 1 minuty do 1 hodiny, celkem přibližně 4 hodiny.
- Stejná událost může přijít víckrát a události nemusí přijít v pořadí. Zpracujte proto každé
idjen jednou a stav vždy čtěte z API. - Po 50 nepovedených doručeních za sebou se webhook vypne. V nastavení uvidíte stav, poslední odpověď a chybu; vypnutý webhook smažte a přidejte znovu.
- Adresa musí být veřejná a používat HTTPS. Soukromé a vyhrazené adresy (například 10.0.0.0/8 nebo 127.0.0.1) se odmítnou.