Skočite na vsebino
Pregled Pregled Novice Novice
Deli

Webhooki in dogodki

Dogodki v realnem času. Dostavljeno s HMAC podpisom.

PaperOffice pokliče vašo končno točko, ko se spremeni dokument, delovni postopek, delovni prostor ali naloga. Brez poliranja.

22 vrstic dogodkov, HMAC-SHA256 podpis, tri strategije ponovnega poskus in dnevnik dostave za vsak poskus.

HMAC-SHA256 pri vsaki dostavi Do 10 ponovitev (standardno 5) Idempotenten po ID-ju dogodka

Razpoložljivi dogodki

22 vrstev dogodkov, razvrščenih po entiteti

Naročite se na posamezne dogodke ali uporabite nadomestni znak * za vse.

Dokumenti

14
  • document.uploaded Nov dokument je bil naložen v delovni prostor
  • document.created Vzdevek za document.uploaded (združljivost)
  • document.processed OCR-/AI-IDP-potek uspešno zaključen
  • document.edited Dokument urejen: posodobljene metapodatke, oznake ali vsebina
  • document.deleted Dokument premaknjen v koš za smeti
  • document.restored Dokument obnovljen iz koša za smeti
  • document.moved Dokument premaknjen med delovnimi prostori
  • document.version_created Nova različica obstoječega dokumenta
  • document.lifecycle_changed Spremenjen status shranjevanja/arhiviranja
  • document.comment_added Ustvarjen komentar k dokumentu
  • document.note_added Priložena notranja opomba
  • document.tag_added Dokumentu dodeljena oznaka
  • document.legal_hold_placed Pravni zadržek aktiviran (nespremenljiv)
  • document.legal_hold_released Pravni zadržek odpravljen

Nalogi

3
  • job.completed Asinhroni nalog uspešno zaključen
  • job.failed Asinhroni nalog končno neuspešen
  • job.progress Napredek pri daljših opravilih

Workspaces

2
  • workspace.shared Delovni prostor je bil deljen z uporabnikom ali ekipo
  • workspace.unshared Dostop do delovnega prostora je bil preklican

Opravila

3
  • task.created Ustvarjeno novo opravilo
  • task.completed Opravilo označeno kot končano
  • task.overdue Rok za opravilo je potekel

Payload in glava

Vsaka dostava sledi istemu vzorcu

Predvidljiv JSON-telo, fiksni HTTP-glave, ISO-8601-UTC časovni žig.

Telo zahtevka

{
  "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
    }
  }
}

Glave HTTP-zahtevka

Glava Primer vrednosti Pomen
Content-Type application/json Vedno JSON, kodiran v UTF-8
User-Agent PaperOffice-Webhook/1.0 Fiksni identifikator za dovoljene sezname požarnega zidu
X-PaperOffice-Event document.processed Vrsta dogodka, ki je bil dostavljen
X-PaperOffice-Event-ID a3b7f9c1… 128-bitni edinstveni ID. Uporabite ga kot ključ za idempotenco.
X-PaperOffice-Subscription-ID 42 ID naročnika, ki prejme dogodek
X-PaperOffice-Signature sha256=… HMAC-SHA256 surovega telesa, heksadecimalno kodirano
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  }'

Preverjanje podpisa

Vsako dostavo preverite z HMAC-SHA256

Izračunajte HMAC-SHA256 nad surovim telesom zahtevka s skupnim skrivnim ključem in primerjajte rezultat z X-PaperOffice-Signature — nujno s konstantnim časom izvajanja.

  • Primerjava s konstantnim časom izvajanja

    hash_equals, hmac.compare_digest ali crypto.timingSafeEqual: Primerjava ne sme razkriti razlik v času izvajanja.

  • Rohen telo podpisati

    Podpis velja za nespremenjeno telo zahteve. JSON razpakirajte šele po preverjanju, sicer se hash razlikuje.

  • Naročilo prek API

    POST /latest/webhooks/subscribe z imenom, URL-jem in dogodki. Če je secret prazen, ga ustvari PaperOffice in ga enkratno vrne.

Poskus znova in dostava

Tri strategije poskusa znova, do 10 ponovitev

Izberite politiko za vsako naročnino. Vsak poskus se dnevnikira s statusno kodo, telesom odziva in časom merjenja.

  • Privzeto exponential

    Eksponentno (privzeto)

    Čas med poskusi se po vsaki neuspeli poskusni ponovitvi podvoji.

  • linear

    Linearno

    Čas med poskusi se poveča za fiksni korak.

  • none

    Brez

    Brez ponovitve, tudi pri napakah 5xx (pošlji in pozabi). Uporabno za testne kaveljčke.

  • Uspeh HTTP 2xx znotraj časovnega okna
  • Največ ponovitev Do 10 ponovitev (privzeto 5)
  • Časovni omejitev 1.000–30.000 ms na poskus (privzeto 10.000)
  • Dnevnik dostave Vsak poskus je zabeležen; dnevnik ostane shranjen tudi po brisanju naročnine.

Upravljanje-API

Pet končnih točk pod /latest/webhooks/

Ustvarjanje, prikazovanje, posodabljanje in brisanje naročnin ter testna končna točka. Vsak klic zahteva Bearer-token.

  • POST /webhooks/subscribe Ustvarite naročnino; podatkovni paketi so podpisani z HMAC-SHA256 Orodje MCPpo-webhooks-subscribe
  • GET /webhooks/list Prikažite vse webhook-naročnine računa Orodje MCPpo-webhooks-list
  • POST /webhooks/update Posodobite URL, dogodke, glave, politiko ponovnega poskusa ali aktivni status Orodje MCPpo-webhooks-update
  • POST /webhooks/delete Odjava naročnine; dnevnik dostave ostane ohranjen Orodje MCPpo-webhooks-delete
  • POST /webhooks/test Pošljite testni dogodek na naročnino in preverite dostavo Orodje MCPpo-webhooks-test

Varnost

Ojačano od osnove

Šest mehanizmov, ki delujejo ob vsaki dostavi — na strani PaperOffice in na vaši.

  • HMAC-SHA256

    Vsaka dostava je podpisana z vašim tajnim ključem. Primerjava mora nujno potekati v konstantnem času.

  • SSRF-zaščita

    Med naročanjem in posredovanjem so blokirane zasebne in notranje IP naslovi, localhost ter končne točke za metapodatke v oblaku.

  • Varno proti DNS rebindingu

    IP naslov se pri posredovanju ponovno preveri in zaklene prek CURLOPT_RESOLVE.

  • HTTPS priporočeno

    Sprejete so protokoli http in https. Za proizvodno okolje priporočamo HTTPS.

  • Idempotenca z ID-jem dogodka

    Vsaka dostava vključuje edinstven X-PaperOffice-Event-ID. Na svoji strani izvedite deduplikacijo.

  • Popolno dnevnik dostave

    Vsi poskusi so zabeleženi: statusna koda, odzivno telo, časovno merjenje, sporočilo o napaki.

Omejitve

Obnašanje pri dostavi je mogoče konfigurirati za vsako naročnino posebej

Vse vrednosti nastavite ob ustvarjanju ali kasneje prek /webhooks/update — za vsako naročnino posebej, ne za račun.

  • 0–10 Ponovitve na dostavo (privzeto 5)
  • 1,000–30,000 ms Časovni omejitev na poskus (privzeto 10.000)
  • 3 Politike ponovnega poskusa: none, linear, exponential
  • HMAC-SHA256 Podpis pri vsaki dostavi

Webhooks so kot razpolago od načrta Professional. Kateri načrt se prilega vašemu nastavitvam, prikazuje pregled cen.

Video

Webhooki v akciji

Oglejte si, kako PaperOffice webhooki delujejo v praksi — v videu.

Webhooki v akciji

Vprašanja

Pogosta vprašanja o webhookih

Kako preverim dostavo?

Izračunajte HMAC-SHA256 nad surovim telesom zahteve s skrivnostjo vaše naročnine in primerjajte rezultat v stalnem času z glavo X-PaperOffice-Signature (format sha256=<hex>). Če podpis ne ustreza, odgovorite s HTTP 401 in ne obdelujte telesa.

Od kod izvira skrivnost?

Ob ustvarjanju naročnine prek POST /latest/webhooks/subscribe. Pustite polje secret prazno, PaperOffice generira skrivnost in jo enkratno vrne v odgovoru. S POST /latest/webhooks/update jo lahko kadar koli nadomestite.

Kaj se zgodi, če moj končni odziv ne odgovori?

Vsak odgovor zunaj HTTP 2xx ali časovna omejitev se šteje kot neuspeh. Glede na politiko ponovnega poskusovanja (eksponentno, linearno, brez) PaperOffice ponovi dostavo do nastavljenega števila ponovitev (0–10, privzeto 5). Vsak poskus je v dnevniku dostave zabeležen s statusno kodo, odgovorom in časovnim merjenjem.

Ali lahko ista dostava prispeta dvakrat?

Da, pri ponovitvah po časovni omejitvi je to mogoče. Zato deduplicirajte preko X-PaperOffice-Event-ID: ID je za vsak dogodek edinstven in se ustreza kot ključ idempotence v vaši bazi podatkov.

Katere dogodke lahko abonirate?

22 vrst dogodkov iz štirih skupin: dokumenti, nalogi, delovni prostori in opravila. Abonirate lahko posamezne dogodke ali z nadomestnim znakom * vse. S filtri (npr. workspace_id ali pofid) dodatno omejite abonma.

V katerem načrtu so webhooki vključeni?

Webhooki so na voljo od načrta Professional. Kateri načrt ustreza vaši nastavitvi, prikazuje pregled cen.

Kje želite preizkusiti PaperOffice?

Računalnik in pametni telefon sta povezana: delovni prostor na računalniku, zajemanje na telefonu.

Vaša preizkusna različica je pripravljena

Kje želite začeti?

Polni delovni prostor je optimiziran za računalnik. Mobilna različica je primerna za zajemanje, pregled in odobrevanje dokumentov.

app.paperoffice.ai

Začni na računalniku

Vašo osebno povezavo za dostav bomo poslali na vaš e-poštni naslov.

Registrirati se brezplačno Odpri aplikacijo Aplikacija PaperOffice Celoten izdelek: splet, namizje in mobilna naprava. Zajemajte, organizirajte, iščite dokumente in delajte nanje s skupino. Potreben je brezplačen račun Odpri Playground Playground Izbrane funkcije takoj — brez registracije, z omejenim demo ključem API. Brez registracije, vendar z omejenim demo ključem API