Přeskočit obsah

Webhooky

Hlavní nabídka Nastavení Webhooky

Práce s webhooky

Webhooky jsou uživatelsky definované HTTP callbacky, které umožňují provést na základě určité události na Vašem dokumentu v Alice definovanou akci. Pokud například chcete propojit Alice s další aplikací, můžete pomocí webhooku zavolat definovanou URL, kde poslouchá jiná aplikace.

Vytvoření webhooku

Webhook nastavíte na stejnojmenné kartě v Nastavení
webhooks
Nový webhook přidáte tlačítkem plus

Vyplňte název webhooku a jeho URL, která se zavolá při spuštění události.
Událost, při které se zavolá webhook, vyberte ze seznamu.

webhook-add

Dostupné události

Událost Popis Kdy se spustí
Dokončení extrakce Po vytěžení dokumentu Automaticky po nahrání a zpracování dokumentu (OCR a rozpoznání dat)
Validace Po validaci dokumentu Při manuálním spuštění validace nebo po každém uložení dokumentu
První validace Po první validaci dokumentu Jednorázově po prvním vytěžení a uložení dat z dokumentu
Uložení Po uložení dokumentu Při každém kliknutí na Uložit
Schválení dokumentu Po schválení Ručně nebo automaticky ve schvalovacím workflow
Zamítnutí dokumentu Po zamítnutí Ručně schvalovatelem ve schvalovacím workflow
Vrácení dokumentu Po vrácení odesílateli Pouze pro dokumenty přijaté emailem
Zahájení workflow Při spuštění schvalovacího procesu Automaticky při zahájení schvalování
Před exportem Před exportem souboru Speciální webhook pro úpravu exportovaného souboru (viz níže)
Vlastní souborový export Vlastní tvorba exportních souborů Umožňuje vytvořit vlastní exportní soubory (viz níže)
Úspěšný export Po úspěšném exportu Po dokončení exportu do účetního systému
Vlastní validace Vlastní validační pravidla Pro implementaci vlastních validačních kontrol

Query požadavku

documentId = ID dokumentu, na kterém událost vznikla

eventType = druh události, která na dokumentu vznikla (viz tabulka)

HTTP požadavek

V požadavku se posílají také parametry (query), která obsahují documentId a eventType

Díky nim můžete identifikovat příchozí volání webhooku.

Pokud je vybrána klientská aplikace, odešle se v požadavku také ID klientské aplikace a token.



Příklad

Můžete například zajistit volání konkrétní URL adresy ihned po vytěžení dokumentu. Např. na adresu https://mojewebhooky.cz/cekamnazavolani, kde může zpracovat požadavek další služba a odeslat upozornění, že došlo k vytěžení dokumentu. example

Aktivace a deaktivace webhooků

Každý webhook můžete kdykoli aktivovat nebo deaktivovat pomocí přepínače Aktivní. Deaktivovaný webhook zůstane uložen v nastavení, ale nebude se spouštět. To je užitečné pro dočasné vypnutí webhooků bez nutnosti je mazat.

Autentizace webhooků

Webhook můžete propojit s klientskou aplikací, která poskytuje přihlašovací údaje (clientId a clientSecret) pro autentizaci požadavků.

Jak nastavit:

  1. Vytvořte klientskou aplikaci v menu Nastavení → Klientské aplikace
  2. Při vytváření webhooku vyberte klientskou aplikaci ze seznamu
  3. Přihlašovací údaje se automaticky připojí ke každému požadavku

Více informací o klientských aplikacích najdete v sekci Klientské aplikace.

Doporučujeme používat HTTPS

Přihlašovací údaje (zejména clientSecret) se přenášejí jako součást URL ve formě query parametrů. Pokud cílová URL nepoužívá HTTPS, mohou být tyto údaje zachyceny třetí stranou.

Důrazně doporučujeme používat výhradně HTTPS adresy pro všechny webhooky, které využívají autentizaci přes klientskou aplikaci.

Formát HTTP požadavku

Formát požadavku se liší podle typu události:

Většina webhooků odesílá HTTP GET požadavek na definovanou URL s query parametry:

GET https://vase-url.cz/webhook?documentId=abc123&eventType=DocumentApproved&clientId=myApp&clientSecret=mySecret

Query parametry:

Parametr Popis
documentId ID dokumentu, který spustil událost
eventType Typ události (např. DocumentApproved, DocumentSaved)
clientId ID klientské aplikace (pokud je nastavena)
clientSecret Secret klientské aplikace (pokud je nastavena)

Webhook typu "Před exportem" odesílá HTTP POST požadavek s JSON tělem:

{
  "DocumentIds": ["abc123"],
  "ExportFormat": "Xml",
  "OriginalFileBase64": "PD94bWwgdmVyc2lvbj0iMS4wIj8+..."
}

JSON pole:

Pole Popis
DocumentIds Seznam ID dokumentů k exportu (obvykle obsahuje jedno ID, při hromadném exportu může obsahovat více ID)
ExportFormat Formát exportu (Pdf, Xml, Isdoc, Csv, atd.)
OriginalFileBase64 Originální exportovaný soubor zakódovaný v Base64

Očekávaná odpověď:

Váš webhook musí vrátit upravený soubor. Tento soubor bude nabídnut uživateli ke stažení místo originálního.

Vlastní souborový export

Událost Vlastní souborový export umožňuje vytvořit vlastní soubory pro export místo standardních formátů.

Jak to funguje:

  1. Při exportu dokumentu Alice zavolá Váš webhook
  2. Váš webhook připraví požadované soubory ke stažení (typicky uložené na vlastním úložišti)
  3. Webhook vrátí seznam souborů, které mají být součástí exportu
  4. Alice tyto soubory použije pro export

Očekávaná odpověď (JSON):

Webhook musí vrátit pole objektů, kde každý objekt popisuje jeden soubor (název a obsah, případně odkaz na obsah):

[
  {
    "fileName": "faktura.xml",
    "content": "<obsah souboru nebo odkaz na obsah>"
  },
  {
    "fileName": "priloha.pdf",
    "content": "<obsah souboru nebo odkaz na obsah>"
  }
]

Cílový systém tedy vrací aplikaci seznam souborů, které se mají v rámci exportu zpracovat.

Technická znalost

Tato funkce vyžaduje technické znalosti a vlastní serverovou aplikaci pro zpracování požadavků.

Pravidla a omezení

  • Název a URL jsou povinné údaje
  • Pouze aktivní webhooky se spouští
  • Webhooky se zpracovávají asynchronně na pozadí, takže nezdržují práci s dokumentem
  • Pokud existuje více webhooků pro stejný typ standardní události (např. Uložení, Schválení dokumentu), spustí se všechny aktivní webhooky pro danou událost
  • Pro událost Před exportem se použije pouze první nalezený aktivní webhook, který odpovídá danému formátu exportu (více webhooků pro stejný formát nemá smysl)
  • Pro událost Vlastní validace se použije pouze první nalezený aktivní webhook
  • Webhook neprovádí automatické opakování při selhání
  • Selhání standardních webhooků neovlivňuje fungování dokumentu
  • Webhook typu "Před exportem" musí vrátit soubor, jinak export selže
  • Webhook typu "Před exportem" se filtruje podle typu události a formátu exportu
  • Není možné nastavit vlastní HTTP hlavičky (například Authorization) - autentizace probíhá výhradně přes query parametry klientské aplikace
  • Webhooky platí pro všechny dokumenty tenanta - není možné je filtrovat podle typu dokumentu, účetní jednotky ani hodnot polí. Pokud potřebujete spouštět logiku jen pro některé dokumenty, musíte filtraci implementovat na straně cílového systému (na základě dat, která si stáhnete z Alice přes API podle documentId)
  • Aplikace neukládá historii volání webhooků ani logy chyb dostupné v uživatelském rozhraní. Pokud potřebujete audit nebo monitoring, musíte ho zajistit na straně cílového systému

Typické příklady použití

Webhooky lze využít pro celou řadu integračních scénářů. Nejčastější příklady jsou shrnuty níže.

Scénář Doporučené řešení Poznámka
Vlastní validace přes externí systém Událost Vlastní validace + zápis výsledků zpět do Alice přes API Technicky náročnější varianta - vyžaduje vlastní serverovou aplikaci a integraci přes API
Transformace exportního souboru Událost Před exportem Vhodné pro přizpůsobení formátu specifickým požadavkům (úprava XML, přidání razítka do PDF, šifrování apod.)
Archivace do vlastního úložiště Událost Vlastní souborový export nebo Úspěšný export Cílový systém dynamicky rozhodne o struktuře archivace (např. složky podle účetní jednotky, roku apod.)

Časté dotazy

Kolik webhooků mohu vytvořit?

Můžete vytvořit libovolný počet webhooků. Pro stejnou událost může existovat více webhooků.

Co se stane, když můj webhook neodpoví?

U standardních webhooků (kromě "Před exportem") selhání webhooků neovlivní práci s dokumentem. Webhook typu "Před exportem" způsobí neúspěšný export, pokud nevrátí soubor.

Jak poznám, který dokument webhook spustil?

ID dokumentu je součástí požadavku (query parametr documentId nebo pole DocumentIds v JSON).

Mohu webhook dočasně vypnout?

Ano, použijte přepínač Aktivní v nastavení webhooku. Deaktivovaný webhook zůstane uložen, ale nebude se spouštět.

Jak zabezpečit webhook?

Použijte klientskou aplikaci pro autentizaci. Přihlašovací údaje (clientId a clientSecret) se automaticky připojí k požadavku.

Jaký formát má identifikátor události (eventType)?

EventType odpovídá internímu názvu události (např. DocumentApproved, ExtractionFinished, DocumentSaved). Tento identifikátor můžete použít pro rozlišení různých událostí.

Mohu upravit více formátů exportu jedním webhookem?

Ne, pro webhook typu "Před exportem" musíte zvolit jeden konkrétní formát. Pokud chcete upravovat více formátů, vytvořte samostatný webhook pro každý formát.

Mohu webhook spustit jen pro některé dokumenty (např. jen faktury)?

Ne, webhooky platí vždy pro všechny dokumenty tenanta. Není možné je filtrovat podle typu dokumentu, účetní jednotky ani hodnot polí.

Pokud potřebujete spouštět logiku jen pro některé dokumenty, proveďte filtraci na straně cílového systému - z parametru documentId si stáhněte detail dokumentu přes API a podle jeho dat se rozhodněte, zda akci provést.

Kde najdu historii volání webhooků?

Aplikace neukládá historii volání ani logy chyb dostupné v uživatelském rozhraní. Pro debugging a audit využijte logy na straně cílového systému.

Webhook "Před exportem"

Událost Před exportem umožňuje transformovat exportní soubor před jeho odesláním do účetního systému nebo před stažením.

Jak to funguje:

  1. Nastavte webhook s událostí "Před exportem"
  2. Vyberte formát exportu ze seznamu (XML, ISDOC, PDF, CSV, atd.)
  3. Při exportu dokumentu v tomto formátu Alice odešle HTTP POST požadavek na Váš webhook
  4. Váš webhook obdrží originální soubor zakódovaný v Base64
  5. Váš webhook zpracuje soubor a vrátí upravený soubor
  6. Alice nabídne ke stažení nebo odešle do účetního systému upravený soubor

Podporované formáty exportu:

  • XML, ISDOC, ISDOCX, PDF
  • CSV, XLSX, JSON
  • Pohoda XML, Money XML, MRP XML, Duel Connector XML
  • Fakturoid CSV, Helios Red CSV
  • Stereo, ZIP

Povinný formát exportu

Pro webhook typu "Před exportem" musíte zvolit konkrétní formát exportu. Webhook se spustí pouze při exportu v tomto formátu.

Filtrování webhooků

Pokud existuje více webhooků typu "Před exportem", spustí se pouze ten, jehož formát exportu odpovídá aktuálnímu exportu.

Důležité upozornění

Pokud Váš webhook selže nebo nevrátí soubor, export dokumentu se nezdaří. Ujistěte se, že webhook funguje správně.

Příklady použití:

  • Přidání razítka nebo podpisu do PDF před stažením
  • Transformace XML do specifického formátu požadovaného účetním systémem
  • Šifrování exportovaných souborů pro zvýšení bezpečnosti
  • Přidání dalších dat do CSV exportu