Ugrás a tartalomra
Áttekintés Áttekintés Hírek Hírek
Megosztás

Webhookok és események

Valós idejű események. HMAC-aláírt kézbesítés.

A PaperOffice azonnal meghívja a végpontját, amint dokumentum, munkafolyamat, munkaterület vagy feladat változik. Nincs lekérdezés (polling).

21 eseménytípus, HMAC-SHA256-aláírás, három retry-stratégia és egy kézbesítési napló minden kísérlethez.

HMAC-SHA256 minden kézbesítésnél Legfeljebb 10 ismétlés (alapértelmezett: 5) Idempotens eseményazonosító alapján

Elérhető események

22 eseménytípus, entitásonként csoportosítva

Iratkozzon fel egyedi eseményekre, vagy használja a * helyettesítője jelet az összeshez.

Dokumentumok

14
  • document.uploaded Új dokumentum feltöltése egy munkaterületre
  • document.created Alias a document.uploaded-hoz (kompatibilitás)
  • document.processed OCR/AI-IDP pipeline sikeresen befejezve
  • document.edited Dokumentum szerkesztése: metaadatok, címkék vagy tartalom frissítve
  • document.deleted Dokumentum a kukába helyezve
  • document.restored Dokumentum visszaállítása a kukából
  • document.moved Dokumentum áthelyezése munkaterületek között
  • document.version_created Meglévő dokumentum új verziója
  • document.lifecycle_changed Megőrzési/archiválási állapot megváltozott
  • document.comment_added Dokumentumhoz komment készült
  • document.note_added Belső jegyzet csatolva
  • document.tag_added Címke dokumentumhoz rendelve
  • document.legal_hold_placed Jogi megőrzés aktiválva (változtathatatlan)
  • document.legal_hold_released Jogi megőrzés feloldva

Feladatok

3
  • job.completed Aszinkron feladat sikeresen befejeződött
  • job.failed Aszinkron feladat véglegesen sikertelen
  • job.progress Folyamatfrissítés hosszabb munkafolyamatoknál

Workspaces

2
  • workspace.shared Munkaterület megosztva felhasználóval vagy csapattal
  • workspace.unshared Munkaterület-hozzáférés visszavonva

Feladatok

3
  • task.created Új feladat létrehozva
  • task.completed Feladat befejezettként megjelölve
  • task.overdue A feladat túllépte a határidőt

Törzs és fejléc

Minden kézbesítés ugyanazt a sémát követi

Előrejelezhető JSON-test, rögzített HTTP-fejlécek, ISO-8601 UTC időbélyeg.

Kérelem-test

{
  "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-kérelem-fejlécek

Fejléc Példaérték Jelentés
Content-Type application/json Mindig JSON, UTF-8 kódolású
User-Agent PaperOffice-Webhook/1.0 Rögzített azonosító tűzfal-engedélyezési listákhoz
X-PaperOffice-Event document.processed Kiszállított eseménytípus
X-PaperOffice-Event-ID a3b7f9c1… 128 bites egyedi azonosító. Használja idempotencia-kulcsként.
X-PaperOffice-Subscription-ID 42 Az eseményt fogló előfizetés azonosítója
X-PaperOffice-Signature sha256=… A nyers törzs HMAC-SHA256 hash-értéke, hexadecimálisan kódolva
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  }'

Aláírás ellenőrzése

Minden kézbesítést HMAC-SHA256-al hitelesítsen

Számítsa ki az HMAC-SHA256 hash-értéket a nyers kérés törzséből a közös titok segítségével, és hasonlítsa össze az eredményt az X-PaperOffice-Signature fejléc értékével — kötelező állandó futási idővel.

  • Állandó futási idejű összehasonlítás

    hash_equals, hmac.compare_digest vagy crypto.timingSafeEqual: Az összehasonlításnak nem szabad futási időbeli különbségeket feltárnia.

  • Rohen Body signálni

    Az aláírás a változatlan request-testre vonatkozik. A JSON-t csak az ellenőrzés után parzolja, különben a hash eltér.

  • Feliratkozás API segítségével

    POST /latest/webhooks/subscribe name, url és events paraméterekkel. Ha a secret üres marad, a PaperOffice generálja és egyszeri alkalommal visszaadja.

Újrapróbálkozás és kézbesítés

Három újrapróbálási stratégia, akár 10 ismétléssel

Válasszon politikát minden előfizetéshez. Minden kísérletet állapotkód, választest és időmérés naplóz.

  • Alapértelmezett exponential

    Exponenciális (alapértelmezett)

    A kísérletek közötti távolság minden sikertelen kísérlet után megduplázódik.

  • linear

    Lineáris

    A kísérletek közötti távolság egy fix lépéssel növekszik.

  • none

    Nincs

    Nincs újrapróbálkozás, még 5xx hibák esetén sem (küldés és elfelejtés). Hasznos teszt-hookokhoz.

  • Siker HTTP 2xx a időkorlát-ablakon belül
  • Max. újrapróbálkozások Akár 10 újrapróbálkozás (alapértelmezett: 5)
  • Időtúllépés 1000–30 000 ms próbánként (alapértelmezett: 10 000)
  • Kézbesítési napló Minden kísérlet naplózásra kerül; a napló megmarad az előfizetés törlése után is.

Kezelési API

Öt végpont a /latest/webhooks/ alatt

Előfizetések létrehozása, listázása, frissítése és törlése — valamint egy tesztvégpont. Minden hívás Bearer-jelölőt tartalmaz.

  • POST /webhooks/subscribe Előfizetés létrehozása; a payloadok HMAC-SHA256-al vannak aláírva MCP-eszközpo-webhooks-subscribe
  • GET /webhooks/list A fiók összes webhook-előfizetésének listázása MCP-eszközpo-webhooks-list
  • POST /webhooks/update URL, események, fejlécek, retry-szabályzat vagy aktív állapot frissítése MCP-eszközpo-webhooks-update
  • POST /webhooks/delete Előfizetés törlése; a kézbesítési napló megmarad MCP-eszközpo-webhooks-delete
  • POST /webhooks/test Teszt esemény küldése egy előfizetésnek és a kézbesítés ellenőrzése MCP-eszközpo-webhooks-test

Biztonság

Az alapoktól megerősítve

Hat mechanizmus, amelyek minden kézbesítésnél érvényesülnek — a PaperOffice oldalán és az Ön oldalán is.

  • HMAC-SHA256

    Minden kézbesítést az Ön titkos kulcsával aláírnak. Az összehasonlításnak szigorúan állandó futási időben kell megtörténnie.

  • SSRF-védelem

    A privát és belső IP-címek, a localhost és a felhőmetadata végpontok letiltásra kerülnek az előfizetés és a dispatch során.

  • DNS-rebinding elleni biztonság

    Az IP-címet a dispatch során újra validálják, és a CURLOPT_RESOLVE segítségével rögzítik.

  • HTTPS ajánlott

    A http és az https elfogadásra kerül. Termelési környezetben az HTTPS használatát javasoljuk.

  • Idempotencia eseményazonosítóval

    Minden kézbesítés egyedi X-PaperOffice-eseményazonosítót tartalmaz. Deduplikálja az oldalon.

  • Teljes kézbesítési napló

    Minden kísérlet naplózva van: státuskód, válasz törzse, időmérés, hibaközlemény.

Korlátok

Szállítási viselkedés előfizetésenként konfigurálható

Az összes értéket az előfizetés létrehozásakor vagy később a /webhooks/update végpont segítségével állíthatja be – előfizetésenként, nem fiókonként.

  • 0–10 Ismétlések szállításonként (alapértelmezett: 5)
  • 1 000–30 000 ms Időtúllépés kísérletenként (alapértelmezett: 10.000)
  • 3 Újrapróbálkozási szabályzatok: none, linear, exponential
  • HMAC-SHA256 Aláírás minden szállításkor

A webhooks a Professional csomagtól érhetők el. Az árlista segít kiválasztani az Ön beállításához illő csomagot.

Videó

Webhookok akcióban

Nézze meg, hogyan működnek a PaperOffice webhookok a gyakorlatban — videóban.

Webhookok akcióban

Kérdések

Webhookokkal kapcsolatos gyakran ismételt kérdések

Hogyan igazolhatom a kézbesítést?

Számítsa ki az HMAC-SHA256-ot az előfizetése titkos kulcsával a nyers kérelem törzsére, és hasonlítsa össze az eredményt állandó futási időben az X-PaperOffice-Signature fejléccel (forma: sha256=<hex>). Ha az aláírás nem egyezik, válaszoljon HTTP 401-gyel, és ne dolgozza fel a törzset.

Honnan származik a titkos kulcs?

Az előfizetés létrehozásakor a POST /latest/webhooks/subscribe hívás során. Ha a 'secret' mezőt üresen hagyja, a PaperOffice generál egy titkos kulcsot, és egyszeri alkalommal visszaadja azt a válaszban. A POST /latest/webhooks/update segítségével bármikor helyettesítheti.

Mi történik, ha az végpont nem válaszol?

Minden válasz, amely nem HTTP 2xx státuskódot ad vissza, vagy időtúllépés esetén az sikertelen kísérletnek számít. A retry-politika (exponenciális, lineáris, nincs) alapján a PaperOffice addig ismétli a kézbesítést, amíg el nem éri a beállított ismétlések számát (0–10, alapértelmezett 5). Minden kísérlet státuskóddal, válasszal és időméréssel szerepel a kézbesítési naplóban.

Ugyanaz a kézbesítés kétszer is megérkezhet?

Igen, az időtúllépés utáni ismétlések miatt ez lehetséges. Ezért deduplikáljon az X-PaperOffice-Event-ID segítségével: az ID eseményenként egyedi, és alkalmas idempotencia-kulcsként az adatbázisában.

Milyen eseményeket iratkozhatok fel?

22 eseménytípus négy csoportból: dokumentumok, munkafolyamatok, munkaterületek és feladatok. Feliratkozhat egyedi eseményekre vagy a * helyettesítő karakterrel az összesre. A szűrők (például workspace_id vagy pofid) segítségével további korlátozásokat is beállíthat.

Melyik csomagban szerepelnek a webhookok?

A webhookok a Professional csomagtól érhetők el. Az árlista megmutatja, melyik csomag illik a beállításaihoz.

Hol szeretné kipróbálni a PaperOffice-t?

A számítógép és az okostelefon összekapcsolva: munkaterület a gépen, rögzítés a telefonon.

A próbaverziója készen áll

Hol szeretne elindulni?

A teljes munkaterület a számítógépre van optimalizálva. A mobil verzió dokumentumok rögzítésére, ellenőrzésére és jóváhagyására alkalmas.

app.paperoffice.ai

Kezdje el számítógépen

Személyes belépési linkjét e-mailben küldjük Önnek.

Nyissa meg a PaperOffice Mobile alkalmazást

Dokumentumok közvetlen rögzítése és szerkesztése okostelefonon.

Mobil verzió megnyitása
Ingyenes regisztráció Alkalmazás megnyitása PaperOffice alkalmazás A teljes termék: web, asztali és mobil. Dokumentumok rögzítése, rendszerezése, keresése és csapatmunka. Ingyenes fiók szükséges Playground megnyitása Playground Kiválasztott funkciók azonnal — regisztráció nélkül, korlátozott demó API-kulccsal. Nincs regisztráció, de korlátozott demó API-kulcs