Šokti į turinį
Apžvalga Apžvalga Naujienos Naujienos
Bendrinti

Webhooks ir įvykiai

Realus laiko įvykiai. Pristatyta su HMAC pasirašymu.

PaperOffice kviečia jūsų galinį tašką iškart, kai pasikeičia dokumentas, užduotis, darbo erdvė ar kita užduotis. Nereikia nuolatinio klausinėjimo (polling).

22 įvykių tipai, HMAC-SHA256 pasirašymas, trys bandymų strategijos ir pristatymo žurnalo įrašas kiekvieno bandymo metu.

HMAC-SHA256 kiekviename pristatyme Iki 10 kartų (standartiškai 5) Idempotenti pagal įvykio ID

Prieinami įvykiai

22 įvykių tipai, sugrupuoti pagal subjektą

Prenumeruokite atskirus įvykius arba naudokite vietos užpildą * visiems.

Dokumentai

14
  • document.uploaded Naujas dokumentas įkeltas į darbo erdvę
  • document.created Alias document.uploaded (suderinamumas)
  • document.processed OCR/AI-IDP valdymo linija sėkmingai baigta
  • document.edited Dokumentas redaguotas: atnaujinti metaduomenys, žymos arba turinys
  • document.deleted Dokumentas perkeltas į šiukšliadėžę
  • document.restored Dokumentas atkurtas iš šiukšliadėžės
  • document.moved Dokumentas perkeltas tarp darbo erdvių
  • document.version_created Nauja esamojo dokumento versija
  • document.lifecycle_changed Pakeistas saugojimo/archyvavimo statusas
  • document.comment_added Sukurtas komentaras prie dokumento
  • document.note_added Pridėtas vidinis užrašas
  • document.tag_added Dokumentui priskirta žyma
  • document.legal_hold_placed Teisinis išsaugojimas įjungtas (nekeičiamas)
  • document.legal_hold_released Teisinis išsaugojimas panaikintas

Užduotys

3
  • job.completed Asinchroninė užduotis sėkmingai baigta
  • job.failed Asinchroninė užduotis galutinai nepavyko
  • job.progress Pažangos atnaujinimas ilgesniuose užduotyse

Workspaces

2
  • workspace.shared Darbo erdvė su vartotoju ar komanda pasidalinta
  • workspace.unshared Prieiga prie darbo erdvės atimta

Užduotys

3
  • task.created Sukurta nauja užduotis
  • task.completed Užduotis pažymėta kaip įvykdyta
  • task.overdue Užduoties įvykdymo terminas viršytas

Turinys ir antraštė

Kiekvienas pristatymas seka tą pačią schemą

Numatomas JSON kūnas, fiksuoti HTTP antraščių laukai, ISO-8601 UTC laiko žyma.

Užklausos kūnas

{
  "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 užklausos antraštės

Antraštė Pavyzdinė reikšmė Reikšmė
Content-Type application/json Visada JSON, UTF-8 koduotas
User-Agent PaperOffice-Webhook/1.0 Fiksuotas identifikatorius firewall leidžiamų sąrašų tikslams
X-PaperOffice-Event document.processed Pristatytas įvykio tipas
X-PaperOffice-Event-ID a3b7f9c1… 128 bitų unikalus ID. Naudokite kaip idempotencijos raktą.
X-PaperOffice-Subscription-ID 42 Prenumeratos ID, gaunanti įvykį
X-PaperOffice-Signature sha256=… Žalių duomenų kūno HMAC-SHA256, koduotas šešioliktainėje sistemoje
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  }'

Parašo patvirtinimas

Patvirtinkite kiekvieną pristatymą naudodami HMAC-SHA256

Apskaičiuokite HMAC-SHA256 pagal žalią užklausos kūną su savo bendru slaptažodžiu ir palyginkite rezultatą su X-PaperOffice-Signature — privaloma naudoti pastovaus laiko palyginimą.

  • Palyginimas pastoviu laiku

    hash_equals, hmac.compare_digest arba crypto.timingSafeEqual: palyginimas neturi atskirti laiko skirtumų.

  • Pasirašyti „Rohen Body“

    Parašas galioja nepakeistam užklausos kūnui. Prieš tikrinimą neanalizuokite JSON, kitaip skaičiuotinis kodas (hash) bus kitoks.

  • Prenumerata per API

    POST /latest/webhooks/subscribe su name, url ir events. Jei secret paliekamas tuščias, „PaperOffice“ jį sugeneruoja ir grąžina vieną kartą.

Pakartotinis bandymas ir pristatymas

Trys pakartotinio bandymo strategijos, iki 10 kartų

Pasirinkite politiką pagal prenumeratą. Kiekvienas bandymas įrašomas į žurnalą su statuso kodu, atsakymo kūnu ir laiko matavimu.

  • Standartinis exponential

    Eksponentinis (numatytasis)

    Atstumas tarp bandymų padvigubėja po kiekvienos nesėkmės.

  • linear

    Linijinis

    Atstumas tarp bandymų didėja pastoviu žingsniu.

  • none

    Nėra

    Jokių pakartojimų, net ir esant 5xx klaidoms (siųsti ir pamiršti). Naudinga testavimo jungtims.

  • Sėkmė HTTP 2xx per laiko limito langą
  • Maks. pakartojimai Iki 10 pakartojimų (numatytasis 5)
  • Laiko limitas 1 000–30 000 ms už bandymą (standartiškai 10 000)
  • Pristatymo žurnalas Kiekvienas bandymas fiksuojamas; protokolas išsaugomas net ir panaikinus prenumeratą.

Valdymo-API

Penki galiniai taškai /latest/webhooks/ kataloge

Sukurkite, sąrašą, atnaujinkite ir panaikinkite prenumeratas – taip pat pateikiamas testavimo galinis taškas. Kiekvienas užklausos siuntimas reikalauja Bearer token.

  • POST /webhooks/subscribe Sukurkite prenumeratą; duomenų paketai pasirašomi naudojant HMAC-SHA256 MCP įrankispo-webhooks-subscribe
  • GET /webhooks/list Sąrašas visų paskyros webhook prenumeratų MCP įrankispo-webhooks-list
  • POST /webhooks/update Atnaujinkite URL, įvykius, antraštes, bandymų politiką arba aktyvumo būseną MCP įrankispo-webhooks-update
  • POST /webhooks/delete Atšaukti prenumeratą; pristatymo protokolas išlieka MCP įrankispo-webhooks-delete
  • POST /webhooks/test Siųsti testinį įvykį prenumeratui ir patikrinti pristatymą MCP įrankispo-webhooks-test

Saugumas

Sukurtas nuo pamatų atsparus

Šeši mechanizmai, veikiantys kiekvieno pristatymo metu — tiek „PaperOffice“ pusėje, tiek jūsų.

  • HMAC-SHA256

    Kiekvienas pristatymas pasirašomas naudojant jūsų slaptažodį (secret). Palyginimas privalo būti atliekamas pastoviu laiko sudėtingumu.

  • SSRF apsauga

    Pristašant ir vykdant siuntimą, blokuojamos privačios ir vidinės IP adresų, localhost bei debesijos metadata galinės taškų.

  • Apsaugota nuo DNS rebindingo

    IP adresas vėl tikrinamas vykdant siuntimą ir užfiksuojamas naudojant CURLOPT_RESOLVE.

  • Rekomenduojamas HTTPS

    Priimami http ir https protokolai. Produktinei aplinkai rekomenduojame naudoti HTTPS.

  • Idempotencija naudojant įvykio ID

    Kiekvienas pristatymas turi unikalų X-PaperOffice-Event-ID. Atlikite deduplikaciją savo pusėje.

  • Išsamus pristatymo žurnalas

    Visi bandymai įrašomi į žurnalą: statuso kodas, atsakymo kūnas, laiko matavimas, klaidos pranešimas.

Ribos

Pristatymo elgsena konfigūruojama pagal prenumeratą

Visas reikšmes nustatykite kuriant arba vėliau per /webhooks/update — kiekvienai prenumeratai atskirai, o ne visam sąskaitai.

  • 0–10 Pakartojimai vieno pristatymo metu (numatyta 5)
  • 1,0–30,0 s Laiko limitas vienam bandymui (numatyta 10.000)
  • 3 Pakartojimo politikos: none, linear, exponential
  • HMAC-SHA256 Parašas kiekvieno pristatymo metu

Webhooks yra prieinami nuo plano Professional. Kuris planas tinka jūsų konfigūracijai, rodo kainų apžvalga.

Vaizdo įrašas

Webhook'ai veiksmo metu

Pažiūrėkite, kaip PaperOffice webhook'ai veikia praktiškai — vaizdo įraše.

Webhook'ai veiksmo metu

Klausimai

Dažniausiai užduodami klausimai apie webhooks

Kaip patvirtinti pristatymą?

Apskaičiuokite HMAC-SHA256 pagal žaliavą request-body su savo prenumeratos slaptažodžiu ir palyginkite rezultatą pastoviu laiku su X-PaperOffice-Signature antrašte (formatas sha256=<hex>). Jei parašas nesutampa, atsakykite HTTP 401 ir neapdorokite body.

Iš kur atsiranda slaptažodis?

Kuriant prenumeratą per POST /latest/webhooks/subscribe. Jei laukas secret paliekamas tuščias, PaperOffice sugeneruoja slaptažodį ir vienkartinį kartą jį grąžina atsakyme. Per POST /latest/webhooks/update jį galima pakeisti bet kada.

Kas nutinka, jei mano galūnė neatsako?

Kiekvienas atsakymas, kuris nėra HTTP 2xx, arba laukimo laikas yra skaičiuojamas kaip nesėkmė. Pagal pakartotinio bandymo politiką (eksponentinė, tiesinė, jokia) PaperOffice kartojia pristatymą iki nustatyto pakartojimų skaičiaus (0–10, numatytasis 5). Kiekvienas bandymas yra užfiksuotas pristatymo žurnale su statuso kodu, atsakymu ir matavimo laiku.

Ar tas pats pristatymas gali atvykti du kartus?

Taip, tai įmanoma pakartojimų po laukimo laikas atveju. Todėl deduplikuokite naudodami X-PaperOffice-Event-ID: ID yra unikalus kiekvienam įvykiui ir tinka kaip idempotencijos raktas jūsų duomenų bazėje.

Kuriuos įvykius galiu prenumeruoti?

22 įvykių tipai iš keturių grupių: dokumentai, užduotys, darbalaukiai ir veiksmai. Galite prenumeruoti individualius įvykius arba visus naudodami žymenį *. Prenumeratą taip pat galite apriboti naudodami filtrus (pvz., workspace_id arba pofid).

Kuriame plane yra įtraukti webhook'ai?

Webhook'ai prieinami nuo plano Professional. Kuris planas tinka jūsų konfigūracijai, rodomas kainų apžvalgoje.

Kur norite išbandyti PaperOffice?

Kompiuteris ir išmanusis telefonas sujungti: darbalaučio funkcijos kompiuteryje, fiksavimas telefone.

Jūsų bandomoji versija paruošta

Kur norite pradėti?

Pilna darbalaučio versija optimizuota kompiuteriui. Mobilioji versija tinka dokumentams fiksuoti, tikrinti ir tvirtinti.

app.paperoffice.ai

Pradėti kompiuteryje

Asmeninį prisijungimo nuorodą atsiųsime į jūsų el. pašto adresą.

Registruotis nemokamai Atidaryti programą PaperOffice programa Visas produktas: žiniatinklis, kompiuteris ir mobilusis. Fiksuokite, tvarkykite, ieškokite dokumentų ir dirbkite su komanda. Reikalinga nemokama paskyra Atidaryti Playground Playground Pasirinktas funkcijas išbandykite iškart — be registracijos, su apribotu demonstraciniu API raktu. Be registracijos, bet su apribotu demonstraciniu API raktu