Přeskočit na obsah
Přehled Přehled Novinky Novinky
Sdílet

Webhooky a události

Události v reálném čase. Doručeno s podpisem HMAC.

PaperOffice zavolá váš koncový bod, jakmile se změní dokument, úkol, pracovní prostor nebo úloha. Žádné dotazování (polling).

22 typů událostí, podpis HMAC-SHA256, tři strategie opakování a protokol doručování pro každý pokus.

HMAC-SHA256 při každém doručení Až 10 opakování (standardně 5) Idempotentní podle ID události

Dostupné události

22 typů událostí, seskupených podle entity

Odebírejte jednotlivé události nebo použijte zástupný symbol * pro všechny.

Dokumenty

14
  • document.uploaded Nový dokument nahrán do pracovního prostoru
  • document.created Alias pro document.uploaded (kompatibilita)
  • document.processed OCR-/AI-IDP-pipeline úspěšně dokončena
  • document.edited Dokument upraven: aktualizována metadata, štítky nebo obsah
  • document.deleted Dokument přesunut do koše
  • document.restored Dokument obnoven z koše
  • document.moved Dokument přesunut mezi pracovními prostory
  • document.version_created Nová verze existujícího dokumentu
  • document.lifecycle_changed Změna stavu uchování/archivace
  • document.comment_added Komentář k dokumentu vytvořen
  • document.note_added Interní poznámka připojena
  • document.tag_added Štítek přiřazen dokumentu
  • document.legal_hold_placed Legal Hold aktivován (neměnný)
  • document.legal_hold_released Legal Hold zrušen

Úkoly

3
  • job.completed Asynchronní úkol úspěšně dokončen
  • job.failed Asynchronní úkol trvale selhal
  • job.progress Aktualizace postupu u delších úloh

Workspaces

2
  • workspace.shared Pracovní prostor sdílen s uživatelem nebo týmem
  • workspace.unshared Zugriff auf den Workspace entzogen

Úkoly

3
  • task.created Nový úkol vytvořen
  • task.completed Úkol označen jako dokončený
  • task.overdue Úkol překročil své datum splnění

Payload a hlavička

Každé doručení následuje stejný schéma

Předvídatelné JSON tělo, pevné HTTP hlavičky, časová značka ISO-8601 UTC.

Tělo požadavku

{
  "event_type": "document.processed",
  "event_id": "a3b7f9c1d4e8b2a6c9f1d4e7b2a5c8f1",
  "timestamp": "2026-04-17T14:23:11Z",
  "subscription_id": 42,
  "data": {
    "pofid": "doc_01HZY8K3M7P2Q9R5T1V6W4X2Y8",
    "workspace_id": 17,
    "filename": "invoice-2026-04-17.pdf",
    "mime_type": "application/pdf",
    "size_bytes": 284521,
    "processing_result": {
      "ocr_done": true,
      "classification": "invoice",
      "confidence": 0.98
    }
  }
}

HTTP hlavičky požadavku

Hlavička Příklad hodnoty Význam
Content-Type application/json Vždy JSON, kódování UTF-8
User-Agent PaperOffice-Webhook/1.0 Pevný identifikátor pro firewall povolené seznamy
X-PaperOffice-Event document.processed Typ doručené události
X-PaperOffice-Event-ID a3b7f9c1… 128bitové unikátní ID. Použijte jej jako klíč pro idempotenci.
X-PaperOffice-Subscription-ID 42 ID předplatného, které událost přijímá
X-PaperOffice-Signature sha256=… HMAC-SHA256 surového těla, hexadecimálně zakódované
cURL
curl -X POST "https://api.paperoffice.ai/latest/webhooks/subscribe" \  -H "Authorization: Bearer po_ut_YOUR_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "name": "My Production Webhook",    "url": "https://yourdomain.com/webhooks/paperoffice",    "events": ["document.processed", "job.completed", "job.failed"],    "retry_policy": "exponential",    "max_retries": 5,    "timeout_ms": 10000  }'

Ověření podpisu

Ověřte každé doručení pomocí HMAC-SHA256

Vypočítejte HMAC-SHA256 přes surový request body s vaším společným tajemstvím a porovnejte výsledek s X-PaperOffice-Signature — povinně s konstantní dobou běhu.

  • Porovnání v konstantní době běhu

    hash_equals, hmac.compare_digest nebo crypto.timingSafeEqual: Porovnání nesmí prozrazovat rozdíly v době běhu.

  • Podepsat tělo požadavku

    Podpis platí pro nezměněné tělo požadavku. Nejprve ověřte podpis a teprve poté parsovejte JSON, jinak se hash liší.

  • Přihlášení pomocí API

    POST /latest/webhooks/subscribe s name, url a events. Pokud necháte secret prázdný, vygeneruje ho PaperOffice a vrátí jej jednorázově.

Opakování a doručení

Tři strategie opakování, až 10 pokusů

Vyberte zásadu pro každé předplatné. Každý pokus se loguje se stavovým kódem, tělem odpovědi a časováním.

  • Výchozí exponential

    Exponenciální (výchozí)

    Odstup mezi pokusy se po každém neúspěchu zdvojnásobí.

  • linear

    Lineární

    Odstup mezi pokusy roste o pevný krok.

  • none

    Žádné

    Žádné opakování, ani u 5xx (odeslat a zapomenout). Užitečné pro testovací hooky.

  • Úspěch HTTP 2xx v rámci časového okna
  • Max. opakování Až 10 opakování (výchozí 5)
  • Časový limit 1 000–30 000 ms na pokus (výchozí 10 000)
  • Protokol doručení Každý pokus je protokolován; protokol zůstává zachován i po odstranění odběru.

Správce-API

Pět koncových bodů pod /latest/webhooks/

Vytvářejte, vypisujte, aktualizujte a odstraňujte odběry — včetně testovacího koncového bodu. Každý požadavek obsahuje bearer token.

  • POST /webhooks/subscribe Vytvořit odběr; payloady jsou podepsány pomocí HMAC-SHA256 Nástroj MCPpo-webhooks-subscribe
  • GET /webhooks/list Vypsat všechny webhookové odběry účtu Nástroj MCPpo-webhooks-list
  • POST /webhooks/update Aktualizovat URL, události, hlavičky, politiku opakování nebo aktivní stav Nástroj MCPpo-webhooks-update
  • POST /webhooks/delete Odebrat předplatné; protokol doručení zůstane zachován Nástroj MCPpo-webhooks-delete
  • POST /webhooks/test Odeslat testovací událost do předplatného a ověřit doručení Nástroj MCPpo-webhooks-test

Bezpečnost

Základně zesílená bezpečnost

Šest mechanismů, které se aktivují při každém doručení — na straně PaperOffice i na vaší straně.

  • HMAC-SHA256

    Každé doručení je podepsáno vaším tajným klíčem (secret). Porovnání musí probíhat v konstantním čase.

  • Ochrana před SSRF

    Soukromé a interní IP adresy, localhost a cloudové metadata endpointy jsou při odebírání a vysílání blokovány.

  • Bezpečné proti DNS rebindingu

    IP adresa je při vysílání znovu ověřena a uzamčena pomocí CURLOPT_RESOLVE.

  • Doporučeno HTTPS

    Akceptovány jsou http i https. Pro provoz v produkci doporučujeme HTTPS.

  • Idempotence pomocí Event-ID

    Každé doručení přináší jedinečnou hlavičku X-PaperOffice-Event-ID. Deduplikujte na své straně.

  • Kompletní protokol doručování

    Všechna pokusy jsou logována: stavový kód, odpovědní tělo, měření času, chybová zpráva.

Limity

Chování doručování lze konfigurovat pro každé předplatné

Všechny hodnoty nastavíte při vytváření nebo později přes /webhooks/update — pro každé předplatné, ne pro účet.

  • 0–10 Opakování na doručení (výchozí 5)
  • 1 000–30 000 ms Časový limit na pokus (výchozí 10.000)
  • 3 Retry politiky: none, linear, exponential
  • HMAC-SHA256 Podpis při každém doručení

Webhooks jsou k dispozici od plánu Professional. Který plán odpovídá vašemu nastavení, ukazuje přehled cen.

Video

Webhooks v akci

Podívejte se, jak PaperOffice webhooks fungují v praxi — ve videu.

Webhooks v akci

Otázky

Často kladené otázky k webhookům

Jak ověřím doručení?

Vypočítejte HMAC-SHA256 přes neupravený tělo požadavku pomocí tajného klíče vašeho předplatného a porovnejte výsledek v konstantním čase s hlavičkou X-PaperOffice-Signature (formát sha256=<hex>). Pokud se podpis neshoduje, odpovězte HTTP 401 a nepracujte s tělem.

Odkud pochází tajný klíč?

Při vytváření předplatného přes POST /latest/webhooks/subscribe. Nechte pole secret prázdné, PaperOffice vygeneruje tajný klíč a vrátí jej jednorázově v odpovědi. Pomocí POST /latest/webhooks/update ho můžete kdykoli nahradit.

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

Každá odpověď mimo HTTP 2xx nebo timeout se počítá jako neúspěšný pokus. V závislosti na politice opakování (exponenciální, lineární, žádné) PaperOffice opakuje doručování až do nastaveného počtu opakování (0–10, výchozí 5). Každý pokaz je v protokolu doručování zaznamenán se stavovým kódem, odpovědí a časovým údajem.

Může stejné doručení přijít dvakrát?

Ano, při opakováních po timeoutu je to možné. Proto deduplikujte pomocí hlavičky X-PaperOffice-Event-ID: ID je pro každý event jedinečné a hodí se jako klíč pro idempotenci ve vaší databázi.

Jaké eventy mohu odebírat?

22 typů eventů ze čtyř skupin: dokumenty, úlohy, workspacy a úkoly. Odebíráte jednotlivé eventy nebo pomocí zástupce * všechny. Pomocí filtrů (např. workspace_id nebo pofid) můžete odběr dále omezit.

V jakém plánu jsou webhooks zahrnuty?

Webhooks jsou k dispozici od plánu Professional. Který plán odpovídá vašemu nastavení, ukazuje přehled cen.

Kde chcete vyzkoušet PaperOffice?

Počítač a smartphone jsou propojeny: workspace na počítači, zachycování na telefonu.

Vaše zkušební verze je připravena

Kde chcete začít?

Plný workspace je optimalizován pro počítač. Mobilní verze se hodí k zachycování, kontrole a schvalování dokumentů.

app.paperoffice.ai

Začněte na počítači

Vaši osobní přístupový odkaz zašleme na vaši e-mailovou adresu.

Registrovat se zdarma Otevřít aplikaci Aplikace PaperOffice Kompletní produkt: web, desktop i mobil. Pořizujte, organizujte, vyhledávejte dokumenty a pracujte na nich s týmem. Je nutný bezplatný účet Otevřít Playground Playground Vybrané funkce ihned — bez registrace, s omezeným demo API klíčem. Bez registrace, ale s omezeným demo API klíčem