Preskočite na sadržaj
Pregled Pregled Novosti Novosti
Podijeli

Webhookovi i događaji

Događaji u stvarnom vremenu. Isporuka s HMAC-potpisom.

PaperOffice poziva vašu krajnju točku čim se dokument, posao, radni prostor ili zadatak promijeni. Bez upitivanja (polling).

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

HMAC-SHA256 pri svakoj isporci Do 10 ponavljanja (standardno 5) Idempotentno po ID-u događaja

Dostupni događaji

22 vrste događaja, grupirane prema entitetu

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

Dokumenti

14
  • document.uploaded Novi dokument je prenesen u radni prostor
  • document.created Alias za document.uploaded (kompatibilnost)
  • document.processed OCR-/AI-IDP-pipeline uspješno završen
  • document.edited Dokument uređen: ažurirani metapodaci, oznake ili sadržaj
  • document.deleted Dokument premješten u smeće
  • document.restored Dokument vraćen iz smeća
  • document.moved Dokument premješten između radnih prostora
  • document.version_created Nova verzija postojećeg dokumenta
  • document.lifecycle_changed Promijenjen status čuvanja/arhiviranja
  • document.comment_added Komentar na dokument dodan
  • document.note_added Interni bilješka priložena
  • document.tag_added Oznaka dodijeljena dokumentu
  • document.legal_hold_placed Pravni zadržavanje aktivirano (nepromjenjivo)
  • document.legal_hold_released Pravni zadržavanje ukinuto

Poslovi

3
  • job.completed Asinkroni posao uspješno završen
  • job.failed Asinkroni posao trajno neuspješan
  • job.progress Napredak ažuriranja za duže poslove

Workspaces

2
  • workspace.shared Radni prostor podijeljen s korisnikom ili timom
  • workspace.unshared Pristup radnom prostoru opozvan

Zadaci

3
  • task.created Stvoren novi zadatak
  • task.completed Zadatak označen kao dovršen
  • task.overdue Rok zadatka istekao

Tijelo i zaglavlje

Svaka isporuka slijedi isti obrazac

Predvidiv tijelo JSON-a, fiksni HTTP zaglavlja, ISO-8601 UTC vremenska oznaka.

Tijelo zahtjeva

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

Zaglavlje Primjer vrijednosti Značenje
Content-Type application/json Uvijek JSON, kodiran u UTF-8
User-Agent PaperOffice-Webhook/1.0 Fiksni identifikator za firewall dopuštenja
X-PaperOffice-Event document.processed Vrsta događaja koji je isporučen
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 tijela, heksadecimalski kodiran
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

Verificirajte svaku dostavu s HMAC-SHA256

Izračunajte HMAC-SHA256 na sirovom tijelu zahtjeva pomoću zajedničkog tajnog ključa i usporedite rezultat s X-PaperOffice-Signature — obavezno s konstantnim vremenom izvršavanja.

  • Usporedba u konstantnom vremenu izvršavanja

    hash_equals, hmac.compare_digest ili crypto.timingSafeEqual: Usporedba ne smije otkriti razlike u vremenu izvršavanja.

  • Potpišite sirovo tijelo zahtjeva

    Potpis vrijedi za nepromijenjeno tijelo zahtjeva. Parsirajte JSON tek nakon provjere, inače će se hash razlikovati.

  • Pretplata putem API

    POST /latest/webhooks/subscribe s imenom, URL-om i događajima. Ostavi li tajna praznom, PaperOffice je generira i vraća je jednokratno.

Ponovni pokušaj i dostava

Tri strategije ponovnog pokušaja, do 10 ponavljanja

Odaberite politiku po pretplati. Svaki pokušaj bilježi se s statusnim kodom, tijelom odgovora i mjerenjem vremena.

  • Standardno exponential

    Eksponencijalno (zadano)

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

  • linear

    Linearno

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

  • none

    Bez ponavljanja

    Bez ponavljanja, čak ni kod 5xx (pošalji i zaboravi). Korisno za testne hookove.

  • Uspjeh HTTP 2xx unutar vremenskog okvira
  • Maks. ponavljanja Do 10 ponavljanja (standardno 5)
  • Vremensko ograničenje 1.000–30.000 ms po pokušaju (standardno 10.000)
  • Dnevnik dostave Svaki pokušaj se bilježi; zapis ostaje sačuvan čak i nakon brisanja pretplate.

Upravljanje-API

Pet krajnjih točaka pod /latest/webhooks/

Stvaranje, popis, ažuriranje i brisanje pretplata — uključujući testnu krajnju točku. Svaki poziv nosi Bearer token.

  • POST /webhooks/subscribe Stvaranje pretplate; payloadi se potpisuju s HMAC-SHA256 MCP-alatpo-webhooks-subscribe
  • GET /webhooks/list Popis svih webhook pretplata računa MCP-alatpo-webhooks-list
  • POST /webhooks/update Ažuriranje URL-a, događaja, zaglavlja, politike ponovnog pokušaja ili aktivnog statusa MCP-alatpo-webhooks-update
  • POST /webhooks/delete Izbrišite pretplatu; protokol dostave ostaje sačuvan MCP-alatpo-webhooks-delete
  • POST /webhooks/test Pošaljite testnu događaj pretplati i provjerite isporuku MCP-alatpo-webhooks-test

Sigurnost

Ojačano od temelja

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

  • HMAC-SHA256

    Svaka isporuka potpisuje se s vašim tajnim ključem. Usporedba mora nužno biti u konstantnom vremenu izvršavanja.

  • SSRF zaštita

    Privatne i interne IP adrese, localhost i cloud metadata endpointi blokirani su tijekom pretplate i slanja.

  • Sigurno protiv DNS rebindinga

    IP adresa se ponovno validira tijekom slanja i fiksira putem CURLOPT_RESOLVE.

  • 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. Dupliciranje izbjegnite na svojoj strani.

  • Potpuni dnevnik isporuke

    Svi pokušaji se logiraju: statusni kod, odgovor tijela, mjerenje vremena, poruka o pogrešci.

Ograničenja

Ponašanje isporuke po pretplati konfigurabilno

Sve vrijednosti postavljate prilikom izrade ili kasnije putem /webhooks/update — po pretplati, ne po računu.

  • 0–10 Ponavljanja po isporuci (standardno 5)
  • 1,00–30,00 ms Vremensko ograničenje po pokušaju (standardno 10.000)
  • 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.

Video

Webhookovi u akciji

Pogledajte kako PaperOffice webhookovi funkcioniraju u praksi — u videu.

Webhookovi u akciji

Pitanja

Često postavljana pitanja o webhookovima

Kako verificiram isporuku?

Izračunajte HMAC-SHA256 preko sirovog tijela zahtjeva sa tajnom vašeg pretplatničkog računa i usporedite rezultat u konstantnom vremenu s zaglavom X-PaperOffice-Signature (format sha256=<hex>). Ako se potpis ne podudara, odgovorite s HTTP 401 i ne obrađujte tijelo.

Odakle dolazi tajna?

Prilikom stvaranja pretplatničkog računa putem POST /latest/webhooks/subscribe. Ostavite polje tajne praznim, PaperOffice će generirati tajnu i jednokratno je vratiti u odgovoru. Preko POST /latest/webhooks/update možete ju zamijeniti u bilo kojem trenutku.

Što se događa ako moj krajnja točka ne odgovori?

Svaki odgovor izvan HTTP 2xx ili timeout broji se kao neuspjeli pokušaj. Ovisno o politici ponovnog pokušaja (eksponencijalna, linearna, niti jedna), PaperOffice ponavlja dostavu do postavljenog broja ponavljanja (0–10, standardno 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 putem 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.

Gdje želite isprobati PaperOffice?

Računalo i pametni telefon povezani: radni prostor na računalu, prikupljanje na telefonu.

Vaša probna verzija je spremna

Gdje želite započeti?

Puni radni prostor optimiziran je za računala. Mobilna verzija prikladna je za prikupljanje, provjeru i odobravanje dokumenata.

app.paperoffice.ai

Započni na računalu

Osobnu poveznicu za pristup poslat ćemo na vašu e-mail adresu.

Otvorite PaperOffice Mobile

Prikupljajte i uređujte dokumente izravno putem pametnog telefona.

Otvori mobilnu verziju
Registrirati se besplatno Otvori aplikaciju Aplikacija PaperOffice Cjelovit proizvod: web, stolno računalo i mobilni uređaj. Snimajte, organizirajte, pretražujte dokumente i radite na njima s timom. Potreban je besplatni račun Otvori Playground Playground Isprobajte odabrane funkcije odmah — bez registracije, s ograničenim demo API ključem. Bez registracije, ali s ograničenim demo API ključem