Skok na sadržaj
Pregled Pregled Vesti Vesti
Podeli

Webhookovi i događaji

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

PaperOffice poziva vašu krajnju tačku čim se dokument, posao, radni prostor ili zadatak promeni. Bez periodičnog upita (polling).

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

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 je otpremljen u radni prostor
  • 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 premešten u korpu za smeće
  • document.restored Dokument je vraćen iz korpe za smeće
  • document.moved Dokument je premešten između radnih prostora
  • 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 Radni prostor je podeljen sa korisnikom ili timom
  • workspace.unshared Pristup radnom prostoru je oduzet

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)
  • 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

    IP adresa se ponovo validira tokom dispatcha 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. 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 (podrazumevano 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

Webhooks u akciji

Pogledajte kako PaperOffice webhooks funkcionira u praksi — u videu.

Webhooks u akciji

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.

Gde želite da isprobate PaperOffice?

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

Vaš probni period je spreman

Gde želite da počnete?

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

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
Registrovati se besplatno Otvori aplikaciju Aplikacija PaperOffice Kompletan proizvod: veb, računar i mobilni uređaj. Snimajte, organizujte, pretražujte dokumente i radite na njima sa timom. Potreban je besplatan nalog Otvori Playground Playground Izabrane funkcije odmah — bez registracije, sa ograničenim demo API ključem. Bez registracije, ali sa ograničenim demo API ključem