Pāriet uz saturu
Pārskats Pārskats Jaunumi Jaunumi
Dalīties

Webhooks un notikumi

Reāllaika notikumi. HMAC-parakstīta piegāde.

PaperOffice izsauc jūsu galapunktu, tiklīdz mainās dokuments, darbs, darba vieta vai uzdevums. Nav nepieciešams regulārs vaicājumu nosūtīšana (polling).

22 notikumu veidi, HMAC-SHA256 paraksts, trīs atkārtotas mēģinājumu stratēģijas un piegādes žurnāls katram mēģinājumam.

HMAC-SHA256 katras piegādes laikā Līdz 10 atkārtojumiem (standarta 5) Idempotents pēc notikuma ID

Pieejamie notikumi

22 notikumu veidi, grupēti pēc entītijas

Abonējiet atsevišķus notikumus vai izmantojiet vietas turošo * visiem.

Dokumenti

14
  • document.uploaded Jauns dokuments augšupielādēts darba telpā
  • document.created Alias document.uploaded (saderība)
  • document.processed OCR/AI-IDP caurteka veiksmīgi pabeigta
  • document.edited Dokuments rediģēts: atjauninātas metadati, etiķetes vai saturs
  • document.deleted Dokuments pārvietots uz papīra grozu
  • document.restored Dokuments atjaunots no papīra groza
  • document.moved Dokuments pārvietots starp darba telpām
  • document.version_created Jauna esoša dokumenta versija
  • document.lifecycle_changed Glabāšanas/arhivēšanas statuss mainīts
  • document.comment_added Dokumentam pievienots komentārs
  • document.note_added Pievienota iekšējā piezīme
  • document.tag_added Dokumentam piešķirts tags
  • document.legal_hold_placed Juridiskā saglabāšana aktivizēta (neizmaināma)
  • document.legal_hold_released Juridiskā saglabāšana atcelta

Uzdevumi

3
  • job.completed Asinhrons uzdevums veiksmīgi pabeigts
  • job.failed Asinhrons uzdevums galīgi neizdevās
  • job.progress Progressa atjauninājums ilgstošos uzdevumos

Workspaces

2
  • workspace.shared Darbvirsma kopīgota ar lietotāju vai komandu
  • workspace.unshared Piekļuve darbvirsmai atsaukta

Uzdevumi

3
  • task.created Izveidots jauns uzdevums
  • task.completed Uzdevums atzīmēts kā pabeigts
  • task.overdue Uzdevuma termiņš ir beidzies

Payload un galvene

Katrs piegādes ziņojums seko vienotam formātam

Paredzams JSON ķermenis, fiksēti HTTP galvenes, ISO-8601 UTC laika zīmogs.

Pieprasījuma ķermenis

{
  "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 pieprasījuma galvenes

Galvene Piemēra vērtība Nozīme
Content-Type application/json Vienmēr JSON, kodēts UTF-8
User-Agent PaperOffice-Webhook/1.0 Fiksēts identifikators ugunsmūra atļauju sarakstiem
X-PaperOffice-Event document.processed Piegādātais notikuma veids
X-PaperOffice-Event-ID a3b7f9c1… 128 bitu unikāls ID. Izmantojiet to kā idempotences atslēgu.
X-PaperOffice-Subscription-ID 42 Abonementa ID, kas saņem notikumu
X-PaperOffice-Signature sha256=… Raw boday HMAC-SHA256, heksadecimāli kodēts
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  }'

Paraksta verifikācija

Verificējiet katru piegādi ar HMAC-SHA256

Aprēķiniet HMAC-SHA256 pār neapstrādāto pieprasījuma boday, izmantojot kopīgo noslēpumu, un salīdziniet rezultātu ar X-PaperOffice-Signature — obligāti ar konstantu laika sarežģītību.

  • Salīdzinājums ar konstantu laika sarežģītību

    hash_equals, hmac.compare_digest vai crypto.timingSafeEqual: Salīdzinājumam nedrīkst atklāt laika atšķirības.

  • Rohen ķermeni parakstīt

    Parakss attiecas uz nemainītu pieprasījuma ķermeni. Parsējiet JSON tikai pēc pārbaudes, citādi hash atšķirsies.

  • Pierakstīšanās ar API

    POST /latest/webhooks/subscribe ar name, url un events. Ja secret ir tukšs, PaperOffice to ģenerē un atgriež vienreizēji.

Atkārtota mēģinājuma un piegāde

Trīs atkārtotu mēģinājumu stratēģijas, līdz 10 atkārtojumiem

Izvēlieties politiku katram pierakstam. Katrs mēģinājums tiek ierakstīts ar statusa kodu, response-body un laika mērījumu.

  • Standarta exponential

    Eksponenciāls (standarts)

    Pārtraukums starp mēģinājumiem dubultojas pēc katra neveiksmīga mēģinājuma.

  • linear

    Lineārs

    Pārtraukums starp mēģinājumiem palielinās par fiksētu soli.

  • none

    Nav

    Nav atkārtotu mēģinājumu, pat pie 5xx (nosūtīt un aizmirst). Noderīgi testēšanas tīmekļa āķiem.

  • Veiksmīgs HTTP 2xx laikā ierobežojuma logā
  • Maks. atkārtoti mēģinājumi Līdz 10 atkārtotiem mēģinājumiem (noklusējums 5)
  • Laika ierobežojums 1 000–30 000 ms uz mēģinājumu (standarta 10 000)
  • Piegādes žurnāls Katrs mēģinājums tiek reģistrēts; žurnāls tiek saglabāts arī pēc abonementa dzēšanas.

Vadības-API

Pieci galapunkti zem /latest/webhooks/

Izveidot, uzskaitīt, atjaunināt un dzēst abonementus — kā arī testēšanas galapunkts. Katrs pieprasījums tiek autentificēts ar Bearer token.

  • POST /webhooks/subscribe Izveidot abonementu; payloadi tiek parakstīti ar HMAC-SHA256 MCP rīkspo-webhooks-subscribe
  • GET /webhooks/list Uzskaitīt visus konta webhook abonementus MCP rīkspo-webhooks-list
  • POST /webhooks/update Atjaunināt URL, notikumus, galvenes, retry politiku vai aktīvo statusu MCP rīkspo-webhooks-update
  • POST /webhooks/delete Atcelt abonementu; piegādes žurnāls tiek saglabāts MCP rīkspo-webhooks-delete
  • POST /webhooks/test Nosūtīt testēšanas notikumu uz abonementu un pārbaudīt piegādi MCP rīkspo-webhooks-test

Drošība

Izturīgs no pamatiem

Seši mehānismi, kas darbojas katras piegādes laikā — gan PaperOffice pusē, gan jūsu pusē.

  • HMAC-SHA256

    Katru piegādi paraksta ar jūsu slepeno atslēgu. Salīdzinājumam ir stingri jānotiek konstantā laika sarežģītībā.

  • SSRF aizsardzība

    Abonējot un izpildot, tiek bloķētas privātās un iekšējās IP adreses, localhost un mākoņa metadatu galapunkti.

  • DNS rebinding drošs

    IP adrese tiek atkārtoti validēta izpildes laikā un fiksēta ar CURLOPT_RESOLVE.

  • HTTPS ieteicams

    Tiek pieņemti http un https. Produktīvā darbībā mēs iesakām HTTPS.

  • Idempotence pēc notikuma ID

    Katrs piegādes mēģinājums satur unikālu X-PaperOffice-Event-ID. Veiciet deduplikāciju savā pusē.

  • Pilns piegādes žurnāls

    Visi mēģinājumi tiek ierakstīti žurnālā: statusa kods, atbildes ķermenis, laika mērījums, kļūdas ziņojums.

Ierobežojumi

Piegādas uzvedību var konfigurēt katram abonementam

Visas vērtības iestatiet, izveidojot abonementu vai vēlāk, izmantojot /webhooks/update — katram abonementam, nevis kontam.

  • 0–10 Atkārtojumi vienā piegādē (standarta 5)
  • 1 000–30 000 ms Laika limits katram mēģinājumam (standarta 10.000)
  • 3 Atkārtotu mēģinājumu politikas: none, linear, exponential
  • HMAC-SHA256 Paraksts katrā piegādē

Webhooks ir pieejami tikai plānā Professional. Kāds plāns atbilst jūsu konfigurācijai, skatiet cenrādī.

Video

Webhooks darbībā

Apskatiet, kā PaperOffice webhooks darbojas praksē — video.

Webhooks darbībā

Jautājumi

Bieži uzdotie jautājumi par webhooks

Kā es varu verificēt piegādi?

Aprēķiniet HMAC-SHA256 pār neapstrādāto request-body ar savu abonementa secret un salīdziniet rezultātu konstantajā laikā ar X-PaperOffice-Signature galveni (format sha256=<hex>). Ja signatūra neatbilst, atbildiet ar HTTP 401 un neapstrādājiet body.

No kurienes nāk secret?

Abonementa izveides laikā caur POST /latest/webhooks/subscribe. Atstājiet lauku secret tukšu, PaperOffice ģenerēs secret un atgriezīs to vienreiz atbildē. Ar POST /latest/webhooks/update varat to aizstāt jebkurā brīdī.

Kas notiek, ja mans endpoints neatbild?

Katrs atbildes kods ārpus HTTP 2xx vai timeout tiek uzskatīts par neveiksmīgu mēģinājumu. Atkarībā no atkārtotu mēģinājumu politikas (eksponenciāla, lineāra, nav) PaperOffice atkārtoti veic piegādi līdz iestatītajam atkārtojumu skaitam (0–10, noklusējums 5). Katrs mēģinājums tiek reģistrēts piegādes žurnālā ar statusa kodu, atbildi un laika mērījumiem.

Vai viena un tā pati piegāde var tikt saņemta divreiz?

Jā, tas ir iespējams atkārtotu mēģinājumu gadījumā pēc timeout. Tādēļ veiciet deduplikāciju, izmantojot X-PaperOffice-Event-ID: ID ir unikāla katram notikumam un piemērota kā idempotences atslēga jūsu datubāzē.

Kurus notikumus es varu abonēt?

22 notikumu veidi no četrām grupām: dokumenti, darbi, darba vietas un uzdevumi. Jūs varat abonēt atsevišķus notikumus vai visus, izmantojot vietnieku *. Ar filtriem (piemēram, workspace_id vai pofid) jūs varat papildus ierobežot abonementu.

Kuros plānos ir iekļauti webhooks?

Webhooks ir pieejami sākot ar plānu Professional. Kurš plāns atbilst jūsu iestatījumam, parāda cenu pārskats.

Kur vēlaties izmēģināt PaperOffice?

Dators un viedtālrunis ir savienoti: darba lauks datorā, fiksēšana telefonā.

Jūsu izmēģinājuma versija ir gatava

Kur vēlaties sākt?

Pilnais darba lauks ir optimizēts datoram. Mobilā versija ir piemērota dokumentu fiksēšanai, pārbaudei un apstiprināšanai.

app.paperoffice.ai

Sākt datorā

Mēs nosūtīsim jūsu personīgo piekļuves saiti uz jūsu e-pasta adresi.

Reģistrēties bez maksas Atvērt lietotni PaperOffice lietotne Pilns produkts: tīmeklis, darbvirsma un mobilā ierīce. Tveriet, kārtojiet, meklējiet dokumentus un strādājiet ar komandu. Nepieciešams bezmaksas konts Atvērt Playground Playground Izmēģiniet atlasītas funkcijas nekavējoties — bez reģistrācijas, ar ierobežotu demo API atslēgu. Bez reģistrācijas, bet ar ierobežotu demo API atslēgu