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í, muž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 každém uložení dokumentu
První validace Po první validaci dokumentu Pouze při prvním uložení 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
Post-processing Post-processing dokumentu Po dokončení zpracování dokumentu
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.

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", "def456"],
  "ExportFormat": "Xml",
  "OriginalFileBase64": "PD94bWwgdmVyc2lvbj0iMS4wIj8+..."
}

JSON pole:

Pole Popis
DocumentIds Seznam ID dokumentů k exportu
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 vytvoří požadované soubory
  3. Webhook vrátí JSON s odkazy na vytvořené soubory
  4. Alice použije tyto soubory pro export

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

[
  {
    "fileName": "faktura.xml",
    "sourceBlobReference": "reference-na-soubor"
  }
]

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í, taktakže nezdržují práci s dokumentem
  • Pokud existuje více webhooků pro stejný typ události, všechny se spustí
  • 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

Č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.

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