Přejít na obsah
FakturanetAPI v1.0.0
OpenAPI API klíče

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álostKdy nastaneObjekt
invoice.createdDoklad vytvořeninvoice
invoice.updatedDoklad upraveninvoice
invoice.issuedDoklad vystaveninvoice
invoice.deletedDoklad smazáninvoice
payment.recordedPlatba zaznamenánainvoice
payment.reversedÚhrada zrušenainvoice
contact.savedKontakt uložencontact
contact.deletedKontakt smazáncontact
expense.savedVýdaj uloženexpense
expense.paidVýdaj zaplacenexpense
expense.deletedVýdaj smazánexpense
export.readyExport připravenexport
export.failedExport se nepodařilexport

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
<?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é id jen 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.

Hledat v dokumentaci

Hledejte endpoint, pole, objekt, typ chyby nebo téma příručky.