Preskočiť na obsah
Prehľad Prehľad Novinky Novinky
Zdieľať

Webhooky a udalosti

Udalosti v reálnom čase. HMAC-signované doručené.

PaperOffice zavolá váš koncový bod, akonáhle sa zmení dokument, úloha, pracovný priestor alebo úloha. Žiadne pollingovanie.

22 typov udalostí, HMAC-SHA256-signatúra, tri stratégie opakovania a protokol doručenia pre každý pokus.

HMAC-SHA256 pri každom doručení Až 10 opakovaní (štandardne 5) Idempotentné podľa ID udalosti

Dostupné udalosti

22 typov udalostí, zoskupených podľa entity

Prihláste sa na jednotlivé udalosti alebo použite zástupný znak * pre všetky.

Dokumenty

14
  • document.uploaded Nový dokument nahraný do pracovného priestoru
  • document.created Alias pre document.uploaded (kompatibilita)
  • document.processed OCR-/AI-IDP-pipeline úspešne dokončená
  • document.edited Dokument upravený: aktualizované metadáta, značky alebo obsah
  • document.deleted Dokument presunutý do koša
  • document.restored Dokument obnovený z koša
  • document.moved Dokument presunutý medzi pracovnými priestormi
  • document.version_created Nová verzia existujúceho dokumentu
  • document.lifecycle_changed Zmenený stav uchovávania/archivovania
  • document.comment_added Komentár k dokumentu vytvorený
  • document.note_added Interná poznámka pripojená
  • document.tag_added Tag priradený k dokumentu
  • document.legal_hold_placed Legal Hold aktivovaný (nezmeniteľný)
  • document.legal_hold_released Legal Hold zrušený

Úlohy

3
  • job.completed Asynchrónna úloha úspešne dokončená
  • job.failed Asynchrónna úloha trvalo zlyhala
  • job.progress Aktualizácia postupu pri dlhších úlohách

Workspaces

2
  • workspace.shared Pracovný priestor zdieľaný s používateľom alebo tímom
  • workspace.unshared Prístup k pracovnému priestoru odobratý

Úlohy

3
  • task.created Vytvorená nová úloha
  • task.completed Úloha označená ako dokončená
  • task.overdue Úloha prekročila termín splnenia

Payload a hlavička

Každé doručenie nasleduje rovnaký schému

Predvídateľné JSON telo, pevné HTTP hlavičky, časová pečiatka v ISO-8601 UTC.

Telo požiadavky

{
  "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žiadavky

Hlavička Príkladná hodnota Význam
Content-Type application/json Vždy JSON, kódované v UTF-8
User-Agent PaperOffice-Webhook/1.0 Pevný identifikátor pre firewallové allowlisty
X-PaperOffice-Event document.processed Typ doručeného eventu
X-PaperOffice-Event-ID a3b7f9c1… 128-bitové unikátne ID. Použite ho ako kľúč pre idempotenciu.
X-PaperOffice-Subscription-ID 42 ID predplatného, ktoré prijíma udalosť
X-PaperOffice-Signature sha256=… HMAC-SHA256 surového tela, hex-kó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  }'

Overenie podpisu

Overte každé doručenie pomocou HMAC-SHA256

Vypočítajte HMAC-SHA256 cez surový request body s vaším spoločným tajomstvom a porovnajte výsledok s X-PaperOffice-Signature — povinne s konštantnou časovou zložitosťou.

  • Porovnanie s konštantnou časovou zložitosťou

    hash_equals, hmac.compare_digest alebo crypto.timingSafeEqual: Porovnanie nesmie prezradiť rozdiely v čase vykonania.

  • Podpísať telo požiadavky Rohen

    Podpis platí pre nezmenené telo požiadavky. Najprv skontrolujte, potom parsovať JSON, inak sa hash líši.

  • Prihlásenie sa cez API

    POST /latest/webhooks/subscribe s názvom, URL a udalosťami. Ak zostane tajomstvo prázdne, PaperOffice ho vygeneruje a vráti ho jednorazovo.

Opakovanie a doručenie

Tri stratégie opakovania, až 10 opakovaní

Vyberte zásadu pre každé predplatné. Každý pokus sa zaznamená so stavovým kódom, telom odpovede a časom.

  • Predvolené exponential

    Exponenciálne (predvolené)

    Časový odstup medzi pokusmi sa po každom neúspechu zdvojnásobí.

  • linear

    Lineárny

    Časový odstup medzi pokusmi sa zväčší o pevný krok.

  • none

    Žiadne

    Žiadne opakovanie, ani pri chybe 5xx (odoslať a zabudnúť). Užitočné pre testovacie hooky.

  • Úspech HTTP 2xx v rámci časového okna
  • Max. opakovania Až 10 opakovaní (predvolené 5)
  • Časový limit 1 000 – 30 000 ms na pokus (predvolené 10 000)
  • Protokol doručenia Každý pokus sa protokoluje; protokol zostáva zachovaný aj po odstránení odberu.

Manažér-API

Päť endpointov pod /latest/webhooks/

Vytvárajte, zoznamujte, aktualizujte a odstraňujte odbery — vrátane testovacieho endpointu. Každý požiadavku obsahuje bearer token.

  • POST /webhooks/subscribe Vytvoriť odber; payloady sú podpísané pomocou HMAC-SHA256 Nástroj MCPpo-webhooks-subscribe
  • GET /webhooks/list Zoznamovať všetky webhookové odbery účtu Nástroj MCPpo-webhooks-list
  • POST /webhooks/update Aktualizovať URL, udalosti, hlavičky, retry politiku alebo aktívny stav Nástroj MCPpo-webhooks-update
  • POST /webhooks/delete Odstrániť predplatné; protokol doručenia zostáva zachovaný Nástroj MCPpo-webhooks-delete
  • POST /webhooks/test Odoslať testovaciu udalosť na predplatné a overiť doručenie Nástroj MCPpo-webhooks-test

Bezpečnosť

Základne spevnené

Šesť mechanizmov, ktoré sa aktivujú pri každom doručení — na strane PaperOffice aj na vašej.

  • HMAC-SHA256

    Každé doručenie je podpísané vaším tajomstvom. Porovnanie musí prebiehať v konštantnom čase.

  • Ochrana pred SSRF

    Súkromné a interné IP adresy, localhost a cloudové metadata endpointy sú blokované pri odberaní aj pri dispatchi.

  • Bezpečné voči DNS rebindingu

    IP adresa sa pri dispatchi znova overí a je uzamknutá pomocou CURLOPT_RESOLVE.

  • Odporúča sa HTTPS

    Akceptujú sa protokoly http aj https. Pre produkčné prostredie odporúčame používať HTTPS.

  • Idempotencia pomocou Event-ID

    Každé doručenie obsahuje jedinečnú hlavičku X-PaperOffice-Event-ID. Na vašej strane vykonajte deduplikáciu.

  • Kompletný protokol doručenia

    Všetky pokusy sú logované: stavový kód, telo odpovede, časovanie, chybová správa.

Obmedzenia

Správanie pri doručovaní je možné konfigurovať podľa predplatného

Všetky hodnoty nastavíte pri vytváraní alebo neskôr cez /webhooks/update — podľa predplatného, nie podľa účtu.

  • 0–10 Opakovania na doručenie (predvolené 5)
  • 1 000–30 000 ms Časový limit na pokus (predvolený 10.000)
  • 3 Politiky opakovania: žiadne, lineárne, exponenciálne
  • HMAC-SHA256 Podpis pri každom doručení

Webhooks sú k dispozícii od plánu Professional. Ktorý plán sa hodí k vášmu nastaveniu, ukazuje prehľad cien.

Video

Webhooky v akcii

Pozrite si, ako PaperOffice webhooky fungujú v praxi — vo videu.

Webhooky v akcii

Otázky

Často kladené otázky o webhookoch

Ako overím doručenie?

Vypočítajte HMAC-SHA256 cez surový request-body s tajomstvom vášho predplatného a porovnajte výsledok v konštantnom čase s hlavičkou X-PaperOffice-Signature (formát sha256=<hex>). Ak sa podpis nezhoduje, odpovedzte HTTP 401 a spracujte telo žiadosti.

Odkiaľ pochádza tajomstvo?

Pri vytváraní predplatného cez POST /latest/webhooks/subscribe. Ak necháte pole secret prázdne, PaperOffice vygeneruje tajomstvo a vráti ho jednorazovo v odpovedi. Pomocou POST /latest/webhooks/update ho môžete kedykoľvek nahradiť.

Čo sa stane, ak môj endpoint neodpovie?

Každá odpoveď mimo HTTP 2xx alebo časový limit sa počíta ako neúspešný pokus. Podľa politiky opakovania (exponenciálna, lineárna, žiadna) opakuje PaperOffice doručovanie až po nastavený počet opakovaní (0–10, predvolené 5). Každý pokaz je v protokole doručovania zaznamenaný so stavovým kódom, odpoveďou a časom.

Môže sa to isté doručenie objaviť dvakrát?

Áno, pri opakovaní po časovom limite je to možné. Preto deduplikujte pomocou hlavičky X-PaperOffice-Event-ID: ID je pre každý event unikátne a vhodná ako kľúč idempotencie vo vašej databáze.

Aké eventy môžem odoberať?

22 typov eventov zo štyroch skupín: dokumenty, úlohy, pracovné priestory a úlohy. Odoberáte jednotlivé eventy alebo so zástupným znakom * všetky. Pomocou filtrov (napr. workspace_id alebo pofid) môžete odber ďalej obmedziť.

V ktorom pláne sú obsiahnuté webhooky?

Webhooky sú k dispozícii od plánu Professional. Ktorý plán sa hodí pre vaše nastavenie, ukazuje prehľad cien.

Kde chcete vyskúšať PaperOffice?

Počítač a smartfón sú prepojené: Pracovný priestor na počítači, zachytávanie na telefóne.

Vaša skúšobná verzia je pripravená

Kde chcete začať?

Plný pracovný priestor je optimalizovaný pre počítač. Mobilná verzia sa hodí na zachytávanie, kontrolu a uvoľňovanie dokumentov.

app.paperoffice.ai

Začať na počítači

Vašu osobnú odkazovú adresu pošleme na vašu e-mailovú adresu.

Registrovať sa zadarmo Otvoriť aplikáciu Aplikácia PaperOffice Kompletný produkt: web, počítač aj mobil. Snímajte, organizujte, vyhľadávajte dokumenty a pracujte na nich s tímom. Je potrebný bezplatný účet Otvoriť Playground Playground Vybrané funkcie ihneď — bez registrácie, s obmedzeným demo API kľúčom. Bez registrácie, ale s obmedzeným demo API kľúčom