Přeskočit na obsah
Otázky?PaperOffice AI Phone Agent 24/7+49 69 3487102-0
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 volá Váš endpoint, jakmile se změní dokument, úkol, Workspace nebo úloha. Žádné dotazování.

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
Události v reálném čase. Doručeno s podpisem HMAC.

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 Workspace
  • 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 smazán; delete_mode zobrazuje trash (koš v Business a Compliance) nebo instant (trvale ve výchozím nastavení)
  • document.restored Dokument obnoven z koše (Business a Compliance)
  • document.moved Dokument přesunut mezi Workspaces
  • 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 Workspace sdíleno 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 (standardně 10 000). První pokus o doručení je v závislosti na události omezen na 2 nebo 5 sekund, opakované pokusy využívají plnou hodnotu.
  • 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

    Cílová adresa je při doručování znovu ověřena.

  • 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 Timeout na pokus (standardně 10 000, první pokus 2–5 s)
  • 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.

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.

Jak se tabulky dostávají do webhooku?

U polí tabulek (například hodnoty inspekcí nebo řádkové položky) document.processed také přenáší data.extracted_tables. Jeho seznam tables obsahuje jeden záznam pro každé pole tabulky s key, label, columns a rows; každá buňka má value (číslo, pokud PaperOffice přečetlo číslo, jinak text vytištěný) a value_raw (text vytištěný, nebo null, pokud není znám). extracted_fields zůstává nezměněno. Každá dodávka obsahuje nejvýše 50 tabulek s až 1 000 řádky a 40 sloupci každá, 2 000 znaků na buňku a 512 KB pro všechny tabulky dohromady; pokud je něco oříznuto, truncated je true a row_count uvádí celkový počet řádků. Podepisuje se celé tělo požadavku, včetně extracted_tables.

Co je nového v události document.processed?

Novinka: key_fields nyní také obsahuje document_number (například číslo faktury) a publisher (vystavitele dokumentu), pokud je PaperOffice přečetl. Položky dokladu přicházejí jako tabulka v data.extracted_tables: tabulka s key __document__content__extraction__line_items (pro pole agenta: _line_items) má jeden řádek na položku dokladu.

PaperOffice AI · Problem Solver

Povězte nám, co Vám denně zabírá čas.

Jednoduše popište. Odborné termíny nejsou potřeba.

Nebo začněte s příkladem

Jak chcete PaperOffice využívat?

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

Kde chcete začít?

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

Registrovat se zdarma app.paperoffice.ai

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

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