Skok na sadržaj
Pitanja?PaperOffice AI Phone Agent 24/7+49 69 3487102-0
Pregled Pregled Vesti Vesti
Podeli

Webhookovi i događaji

Događaji u realnom vremenu. HMAC-potpisano isporučeno.

PaperOffice poziva vaš endpoint čim se dokument, posao, Workspace ili zadatak promeni. Bez upitivanja.

22 tipa događaja, HMAC-SHA256-potpis, tri strategije ponovnog pokušaja i dnevnik isporuke po pokušaju.

HMAC-SHA256 pri svakoj isporuci Do 10 ponavljanja (standardno 5) Idempotentno po ID-u događaja
Događaji u realnom vremenu. HMAC-potpisano isporučeno.

Dostupni događaji

22 vrste događaja, grupisane po entitetu

Pretplatite se na pojedinačne događaje ili koristite placeholder * za sve.

Dokumenti

14
  • document.uploaded Novi dokument otpremljen u Workspace
  • document.created Alias za document.uploaded (kompatibilnost)
  • document.processed OCR-/AI-IDP-pipeline uspešno završen
  • document.edited Dokument izmenjen: ažurirani metapodaci, oznake ili sadržaj
  • document.deleted Dokument je obrisano; delete_mode prikazuje trash (korpa za smeće u Business i Compliance) ili instant (trajno u podrazumevanom)
  • document.restored Dokument je vraćen iz korpe za smeće (Business i Compliance)
  • document.moved Dokument premješten između Workspaces
  • document.version_created Nova verzija postojećeg dokumenta
  • document.lifecycle_changed Promenjen status čuvanja/arhiviranja
  • document.comment_added Komentar na dokumentu kreiran
  • document.note_added Interna napomena priložena
  • document.tag_added Oznaka dodeljena dokumentu
  • document.legal_hold_placed Pravni zadržaj aktiviran (nepromenljiv)
  • document.legal_hold_released Pravni zadržaj ukinut

Poslovi

3
  • job.completed Asinhroni posao uspešno završen
  • job.failed Asinhroni posao trajno neuspešan
  • job.progress Ažuriranje napretka za duže poslove

Workspaces

2
  • workspace.shared Workspace podeljen sa korisnikom ili timom
  • workspace.unshared Workspace pristup opozvan

Zadaci

3
  • task.created Kreiran novi zadatak
  • task.completed Zadatak označen kao završen
  • task.overdue Rok za zadatak je istekao

Payload i zaglavlje

Svaka isporuka prati isti šablon

Predvidiv JSON telo, fiksni HTTP zaglavlja, ISO-8601 UTC vremenski žig.

Telo zahteva

{
  "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 zaglavlja zahteva

Zaglavlje Primer vrednosti Značenje
Content-Type application/json Uvek JSON, UTF-8 kodiran
User-Agent PaperOffice-Webhook/1.0 Fiksni identifikator za firewall allow-liste
X-PaperOffice-Event document.processed Tip dostavljenog događaja
X-PaperOffice-Event-ID a3b7f9c1… 128-bitni jedinstveni ID. Koristite ga kao ključ za idempotenciju.
X-PaperOffice-Subscription-ID 42 ID pretplate koja prima događaj
X-PaperOffice-Signature sha256=… HMAC-SHA256 sirovog tela zahteva, heksadecimalski 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  }'

Verifikacija potpisa

Verifikujte svaku isporuku pomoću HMAC-SHA256

Izračunajte HMAC-SHA256 preko sirovog tela zahteva koristeći zajednički tajni ključ i uporedite rezultat sa X-PaperOffice-Signature — obavezno sa konstantnim vremenom izvršavanja.

  • Upoređivanje u konstantnom vremenu izvršavanja

    hash_equals, hmac.compare_digest ili crypto.timingSafeEqual: Upoređivanje ne sme otkriti razlike u vremenu izvršavanja.

  • Potpisati telo zahteva

    Potpis važi za nepromenjeno telo zahteva. Parsirajte JSON tek nakon provere, inače će se hash razlikovati.

  • Pretplata putem API

    POST /latest/webhooks/subscribe sa name, url i events. Ako ostavite secret praznim, PaperOffice ga generiše i vraća jedinstveno.

Ponovni pokušaj i isporuka

Tri strategije ponovnog pokušaja, do 10 ponavljanja

Odaberite politiku po pretplati. Svaki pokušaj se beleži sa statusnim kodom, telom odgovora i merenjem vremena.

  • Standardno exponential

    Eksponencijalno (standardno)

    Razmak između pokušaja se udvostručuje nakon svakog neuspeha.

  • linear

    Linearno

    Razmak između pokušaja raste za fiksni korak.

  • none

    Bez ponavljanja

    Bez ponavljanja, čak ni kod grešaka 5xx (pošalji i zaboravi). Korisno za test hook-ove.

  • Uspeh HTTP 2xx unutar vremenskog okvira
  • Maks. ponavljanja Do 10 ponavljanja (podrazumevano 5)
  • Prekoračenje vremena 1.000–30.000 ms po pokušaju (standardno 10.000). Prvi pokušaj isporuke ograničen je na 2 ili 5 sekundi u zavisnosti od događaja; ponavljanja koriste punu vrednost.
  • Dnevnik dostave Svaki pokušaj se beleži; dnevnik ostaje sačuvan i nakon brisanja pretplate.

Upravljanje-API

Pet krajnjih tačaka pod /latest/webhooks/

Kreirajte, prikažite, ažurirajte i obrišite pretplate — uključujući testnu krajnju tačku. Svaki poziv zahteva Bearer token.

  • POST /webhooks/subscribe Kreirajte pretplatu; payloadi se potpisuju HMAC-SHA256 algoritmom MCP alatpo-webhooks-subscribe
  • GET /webhooks/list Prikažite sve webhook pretplate naloga MCP alatpo-webhooks-list
  • POST /webhooks/update Ažurirajte URL, događaje, zaglavlja, politiku ponovnog pokušaja ili status aktivnosti MCP alatpo-webhooks-update
  • POST /webhooks/delete Otkazivanje pretplate; protokol dostave ostaje sačuvan MCP alatpo-webhooks-delete
  • POST /webhooks/test Slanje testne događaja pretplati i provera isporuke MCP alatpo-webhooks-test

Bezbednost

Ojačano od osnove

Šest mehanizama koji se aktiviraju pri svakoj isporuci — na strani PaperOffice-a i na vašoj.

  • HMAC-SHA256

    Svaka isporuka se potpisuje sa vašim tajnim ključem. Poređenje mora nužno da se izvrši u konstantnom vremenu.

  • SSRF zaštita

    Privatne i interne IP adrese, localhost i cloud metadata endpointi se blokiraju prilikom pretplate i dispatcha.

  • DNS rebinding siguran

    Adresa odredišta se ponovo proverava u trenutku isporuke.

  • HTTPS preporučeno

    Prihvaćaju se http i https. Za proizvodnu upotrebu preporučujemo HTTPS.

  • Idempotnost putem Event-ID

    Svaka isporuka donosi jedinstvenu X-PaperOffice-Event-ID. Duplicirajte na svojoj strani.

  • Kompletni dnevnik isporuke

    Svi pokušaji se loguju: statusni kod, response telo, merenje vremena, poruka o grešci.

Ograničenja

Ponašanje isporuke po pretplati konfigurabilno

Sve vrednosti postavljate prilikom kreiranja ili kasnije putem /webhooks/update — po pretplati, ne po nalogu.

  • 0–10 Ponavljanja po isporuci (podrazumevano 5)
  • 1,0–30,0 s Vreme čekanja po pokušaju (standardno 10.000, prvi pokušaj 2–5 s)
  • 3 Politike ponovnog pokušaja: none, linear, exponential
  • HMAC-SHA256 Potpis pri svakoj isporuci

Webhooks su dostupni od plana Professional. Koji plan odgovara vašem postavu, prikazuje pregled cijena.

Pitanja

Česta pitanja o webhookovima

Kako da verificiram isporuku?

Izračunajte HMAC-SHA256 preko sirovog tijela zahtjeva sa tajnom vašeg pretplatnika i uporedite rezultat u konstantnom vremenu sa zaglavljem X-PaperOffice-Signature (format sha256=<hex>). Ako potpis ne odgovara, odgovorite sa HTTP 401 i ne obrađujte tijelo.

Odakle dolazi tajna?

Prilikom kreiranja pretplate putem POST /latest/webhooks/subscribe. Ostavite polje secret praznim, PaperOffice će generisati tajnu i vratiti je jednokratno u odgovoru. Preko POST /latest/webhooks/update možete je zamijeniti u bilo kojem trenutku.

Šta se dešava ako moj endpoint ne odgovori?

Svaki odgovor izvan HTTP 2xx ili timeout broji se kao neuspjeli pokušaj. Ovisno o politici ponovnog pokušaja (eksponencijalna, linearna, niti), PaperOffice ponavlja dostavu do postavljenog broja ponavljanja (0–10, standard 5). Svaki pokušaj zabilježen je u dnevniku dostave s statusnim kodom, odgovorom i mjerenjem vremena.

Može li ista dostava stići dvaput?

Da, moguće je kod ponavljanja nakon timeouta. Zato deduplicirajte putem X-PaperOffice-Event-ID: ID je jedinstven za svaki događaj i prikladan kao ključ idempotencije u vašoj bazi podataka.

Koje događaje mogu pretplatiti?

22 vrste događaja iz četiri grupe: dokumenti, poslovi, radni prostori i zadaci. Pretplatite se na pojedinačne događaje ili sa zamjenikom * na sve. Dodatno ograničite pretplatu pomoću filtera (npr. workspace_id ili pofid).

U kojem planu su webhooks uključeni?

Webhooks su dostupni od plana Professional. Koji plan odgovara vašem postavu, prikazuje pregled cijena.

Kako tabele stižu u webhook?

Za polja tabela (na primer, vrednosti inspekcije ili stavke), document.processed takođe sadrži data.extracted_tables. Njegov spisak tables sadrži po jedan unos za svako polje tabele sa key, label, columns i rows; svaka ćelija ima value (broj ako je PaperOffice pročitao broj, inače tekst onako kako je odštampan) i value_raw (tekst onako kako je odštampan, ili null ako nije poznato). extracted_fields ostaje nepromenjeno. Svaka isporuka sadrži najviše 50 tabela sa do 1.000 redova i 40 kolona svaka, 2.000 karaktera po ćeliji i 512 KB za sve tabele zajedno; ako je nešto odsečeno, truncated je true, a row_count navodi ukupan broj redova. Potpis pokriva celo telo zahteva, uključujući extracted_tables.

Šta je novo u događaju document.processed?

Novo: key_fields sada takođe sadrži document_number (na primer, broj fakture) i publisher (izdavalac dokumenta), ako ih je pročitao PaperOffice. Stavke dolaze kao tabela u data.extracted_tables: tabela sa key __document__content__extraction__line_items (za polja agenta: _line_items) ima jedan red po stavci.

PaperOffice AI · Problem Solver

Ispričajte nam, šta vam svakodnevno oduzima vreme.

Jednostavno opišite. Nisu potrebni stručni termini.

Ili započnite sa primerom

Kako želite da koristite PaperOffice?

Računar i pametni telefon su povezani: radni prostor na računaru, prikupljanje na telefonu.

Gde želite da počnete?

Puna verzija radnog prostora optimizovana je za računare. Mobilna verzija je pogodna za prikupljanje, proveru i odobravanje dokumenata.

Registrovati se besplatno app.paperoffice.ai

Započnite na računaru

Poslaćemo vaš lični link za pristup na vašu e-mail adresu.

Otvorite PaperOffice Mobile

Prikupljajte i obrađujte dokumente direktno putem pametnog telefona.

Otvori mobilnu verziju