Liikuge sisu juurde
Ülevaade Ülevaade Uudised Uudised
Jaga

Webhookid ja sündmused

Reaalajasündmused. HMAC-allkirjastatud kohaletoimetamine.

PaperOffice kutsub teie lõpppunkti, kui dokument, töö, tööruum või ülesanne muutub. Pole vaja pordida.

22 sündmustüüpi, HMAC-SHA256-allkiri, kolm taaskatsestrateegiat ja kohaletoimetamise logi iga katse kohta.

HMAC-SHA256 igal kohaletoomisel Kuni 10 kordust (standardne 5) Idempotentne sündmus-ID järgi

Saadaval olevad sündmused

22 sündmuse tüüpi, grupeeritud üksuse järgi

Tellige üksikuid sündmusi või kasutage kõigi jaoks asetäitjat *.

Dokumendid

14
  • document.uploaded Uus dokument laaditi tööruumi üles
  • document.created Alias document.uploaded jaoks (ühilduvus)
  • document.processed OCR-/AI-IDP-pipeline edukalt lõpetatud
  • document.edited Dokument redigeeritud: värskendatud metaandmed, sildid või sisu
  • document.deleted Dokument viidud prügikasti
  • document.restored Dokumendi taastamine prügikastist
  • document.moved Dokumendi ülekandmine tööruumide vahel
  • document.version_created Olemasoleva dokumendi uus versioon
  • document.lifecycle_changed Säilitamis-/arhiveerimisstaatus muutunud
  • document.comment_added Dokumendile lisatud kommentaar
  • document.note_added Sisemine märkus lisatud
  • document.tag_added Dokumendile määratud silt
  • document.legal_hold_placed Õiguslik hoidmine aktiveeritud (muutmata)
  • document.legal_hold_released Õiguslik hoidmine tühistatud

Tööd

3
  • job.completed Asünkroonne töö edukalt lõpetatud
  • job.failed Asünkroonne töö lõplikult nurjunud
  • job.progress Edasiminek uuendus pikemate tööde puhul

Workspaces

2
  • workspace.shared Tööruum jagatud kasutaja või meeskonnaga
  • workspace.unshared Tööruumi ligipääs tühistatud

Ülesanded

3
  • task.created Uus ülesanne loodud
  • task.completed Ülesanne märgitud lõpetatuks
  • task.overdue Ülesanne on ületanud tähtaaja

Sisu ja päis

Iga kohaletoimetamine järgib sama skeemi

Ettearvatatav JSON-kere, kindlad HTTP-päised, ISO-8601-UTC-aegsilt.

Päringukere

{
  "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-päringupäised

Päis Näiteväärtus Mõte
Content-Type application/json Alati JSON, UTF-8-kodeeritud
User-Agent PaperOffice-Webhook/1.0 Kindel identifikaator tulemüüri lubatud loendite jaoks
X-PaperOffice-Event document.processed Kohaletoimetatud sündmuse tüüp
X-PaperOffice-Event-ID a3b7f9c1… 128-bitine unikaalne ID. Kasutage seda idempotentsusvõtmena.
X-PaperOffice-Subscription-ID 42 Tellimuse ID, mis saab sündmuse
X-PaperOffice-Signature sha256=… Raw-bodyle HMAC-SHA256, hex-kodeeritud
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  }'

Allkirja kontrollimine

Kontrollige igat kohaletoimetamist HMAC-SHA256-ga

Arvutage HMAC-SHA256 algse päringu keha põhjal oma ühise saladusega ja võrrelge tulemust X-PaperOffice-Signature-ga — hädavajalik konstantse käitajaajaga.

  • Konstantse käitajaaja võrdlus

    hash_equals, hmac.compare_digest või crypto.timingSafeEqual: Võrdlus ei tohi paljastada käitajaaja erinevusi.

  • Rohen Body signeerida

    Allkiri kehtib muutmata request-body jaoks. Parsige JSON alles pärast kontrollimist, muidu hash erineb.

  • Tellige API kaudu

    POST /latest/webhooks/subscribe koos nime, url ja events-ga. Kui secret jääb tühjaks, genereerib PaperOffice selle ja annab selle ühekordselt tagasi.

Taaskatse ja kohaletoimetamine

Kolm taaskatse strateegiat, kuni 10 kordust

Valige poliitika tellimuse kohta. Iga katse logitakse koos staatusekoodi, vastuse body ja ajamõõtmisega.

  • Vaikimisi exponential

    Eksponentsiaalne (vaikimisi)

    Püüete vaheline vahe kahekordistub pärast iga ebaõnnestunud püüet.

  • linear

    Lineaarne

    Püüete vaheline vahe kasvab kindla sammuga.

  • none

    Puudub

    Ühtegi kordamist ei tehta, isegi 5xx korral (saatke ja unustage). Kasulik test-hookide jaoks.

  • Edasikiri HTTP 2xx ajavahemiku piires
  • Maks. kordamised Kuni 10 kordamist (vaikimisi 5)
  • Ajakõlblikkus 1 000–30 000 ms pro katse (vaikimisi 10 000)
  • Kohaletoimetamise logi Iga katse logitakse; logige säilib ka pärast tellingu kustutamist.

Juhtimine-API

Viis otspunkti aadressil /latest/webhooks/

Tellimuste loomine, loetlemine, uuendamine ja kustutamine — lisaks testotspunkt. Iga päring sisaldab Bearer-tokenit.

  • POST /webhooks/subscribe Looge tellimus; payloadid allkirjastatakse HMAC-SHA256-ga MCP-tööriistpo-webhooks-subscribe
  • GET /webhooks/list Loetle konto kõik webhook-tellimused MCP-tööriistpo-webhooks-list
  • POST /webhooks/update Uuendage URLi, sündmusi, päiseid, retry-poliitikat või aktiivse staatuse MCP-tööriistpo-webhooks-update
  • POST /webhooks/delete Tellige tühistamine; kohaletoimetamise logi säilib MCP-tööriistpo-webhooks-delete
  • POST /webhooks/test Saatke testüritus tellijale ja kontrollige kohaletoimetamist MCP-tööriistpo-webhooks-test

Turvalisus

Alates alusest tugevdatud

Kuus mehhanismi, mis iga kohaletoimetamise käigus toimivad — PaperOffice'i poolel ja teie poolel.

  • HMAC-SHA256

    Iga kohaletoimetamine allkirjastatakse teie saladusega. Võrdlus peab toimuma kindlas ajas.

  • SSRF-kaitse

    Avalikud ja sisemised IP-aadressid, localhost ning pilvemetaandite lõpppunktid on tellimise ja saatmise ajal blokeeritud.

  • DNS-rebindingu ohutu

    IP-aadress saadete ajal uuesti valideeritakse ja CURLOPT_RESOLVE abil fikseeritakse.

  • HTTPS soovitatav

    Aksepteeritakse nii http kui ka https. Tootmiskeskkonna jaoks soovitame HTTPS-i.

  • Idempotentsus sündmi ID-ga

    Iga saatmine sisaldab unikaalset X-PaperOffice-sündmi ID-d. Tehke deduplikatsioon oma poolel.

  • Täielik saatmislogi

    Kõik katsed logitakse: olekukood, vastuse keha, ajastus, veateade.

Piirid

Kohaletoomiskäitumist saab igas tellimuses eraldi konfigureerida

Väärtused määratakse tellimuse loomisel või hiljem läbi /webhooks/update — igas tellimuses eraldi, mitte kogu konto jaoks.

  • 0–10 Kordused ühe kohaletoomise kohta (vaikimisi 5)
  • 1 000–30 000 ms Aegumine ühe katse kohta (vaikimisi 10.000)
  • 3 Taaskatse poliitikad: none, linear, exponential
  • HMAC-SHA256 Allkiri igal kohaletoomisel

Webhooks on saadaval alates plaanist Professional. Milline plaan sobib teie seadistusega, näitab hinnakiri.

Video

Webhooks tegevuses

Vaadake, kuidas PaperOffice webhookid praktikas toimivad — videos.

Webhooks tegevuses

Küsimused

Korduma kippuvad küsimused webhookide kohta

Kuidas ma kinnitan kohaletoimetamist?

Arvutage HMAC-SHA256 algse päringukeha põhjal, kasutades oma tellimuse saladust, ja võrrelge tulemust konstantses ajas päise X-PaperOffice-Signature väärtusega (vorming sha256=<hex>). Kui allkiri ei kattu, vastake HTTP 401-ga ja ärge töötlege keha.

Kust ma saan saladuse?

Tellimuse loomisel POST /latest/webhooks/subscribe kaudu. Jätke väli 'secret' tühjaks, siis genereerib PaperOffice saladuse ja tagastab selle üks kord vastuses. Saate selle igal ajal asendada POST /latest/webhooks/update abil.

Mis juhtub, kui minu lõpppunkt ei vasta?

Iga vastus väljaspool HTTP 2xx või ajakõlblikkus loob ebaõnnestunud katse. Sõltuvalt taaskatse poliitikast (eksponentsiaalne, lineaarne, puudub) kordab PaperOffice kohaletoimetamist kuni seatud taaskatsete arvuni (0–10, vaikimisi 5). Iga katse on kohaletoimetamise logis koos staatusekoodi, vastuse ja ajastusega.

Kas sama kohaletoimetamine võib tulla kaks korda?

Jah, taaskatsete korral pärast ajalõppu on see võimalik. Seetõttu deduplitseerige X-PaperOffice-Event-ID kaudu: ID on sündmuse kaupa unikaalne ja sobib idempotentsusvõtmena teie andmebaasis.

Milliseid sündmusi saan tellida?

22 sündmustüüpi neljast rühmast: dokumendid, tööd, tööruumid ja ülesanded. Saate tellida üksikuid sündmusi või kasutades asetäitjat * kõiki. Filtrite (nt workspace_id või pofid) abil saate tellimust täiendavalt piirata.

Millises plaanis on webhookid sisaldatud?

Webhookid on saadaval alates plaanist Professional. Milline plaan teie seadistusele sobib, näitab hinnakiri.

Kus soovite PaperOffice’i proovida?

Arvuti ja nutitelefon on ühendatud: töölaud arvutis, salvestamine telefonis.

Teie prooviperiood on valmis

Kus soovite alustada?

Täielik töölaud on arvutiga optimeeritud. Mobiiliversioon sobib dokumentide salvestamiseks, kontrollimiseks ja heakskiitmiseks.

app.paperoffice.ai

Alusta arvutis

Saadame teie isikliku ligipääsulingi teie e-posti aadressile.

Registreeruda tasuta Ava rakendus PaperOffice’i rakendus Täielik toode: veeb, töölaud ja mobiil. Jäädvustage, korraldage, otsige dokumente ja töötage nendega koos meeskonnaga. Vajalik on tasuta konto Ava Playground Playground Proovige valitud funktsioone kohe — ilma registreerimiseta, piiratud demo-API-võtmega. Ilma registreerimiseta, kuid piiratud demo-API-võtmega