Webhooks și Evenimente

Evenimente în timp real. Semnate HMAC livrate.

Name: Evenimente în timp real. Semnate HMAC livrate.
Uploaded: 2026-10-19T21:09:20.225Z
Description: Evenimente în timp real. Semnate HMAC livrate.

PaperOffice apelează punctul dumneavoastră de terminare imediat ce un document, job, Workspace sau sarcină se schimbă. Fără interogare periodică.

22 tipuri de evenimente, semnătură HMAC-SHA256, trei strategii de reîncercare și un jurnal de livrare per încercare.

Abonare la primul webhook Lansarea primului apel API

HMAC-SHA256 la fiecare livrare Până la 10 repetări (standard 5) Idempotent per ID de eveniment

Evenimente în timp real. Semnate HMAC livrate.

Infrastructură proprie UE Datele dumneavoastră rămân în Europa.
ISO/IEC 27001 certificat Securitate certificată.
Peste 24 de ani de experiență Dovedită. Stabilă. Pregătită pentru viitor.

Evenimente disponibile

22 tipuri de evenimente, grupate după entitate

Abonați-vă la evenimente individuale sau utilizați caracterul wildcard * pentru toate.

Documente

document.uploaded Document nou încărcat într-un Workspace
document.created Alias pentru document.uploaded (compatibilitate)
document.processed Pipeline OCR/AI-IDP finalizat cu succes
document.edited Document editat: metadate, etichete sau conținut actualizat
document.deleted Document șters; delete_mode indică trash (Coș de gunoi în Business și Compliance) sau instant (definitiv în standard)
document.restored Document restaurat din coșul de gunoi (Business și Compliance)
document.moved Document mutat între Workspaces
document.version_created Versiune nouă a unui document existent
document.lifecycle_changed Starea de păstrare/arhivare modificată
document.comment_added Comentariu adăugat la un document
document.note_added Notă internă atașată
document.tag_added Etichetă atribuită unui document
document.legal_hold_placed Legal Hold activat (imutabil)
document.legal_hold_released Legal Hold ridicat

Joburi

job.completed Job async finalizat cu succes
job.failed Job async eșuat definitiv
job.progress Actualizare progres pentru job-uri lungi

Workspaces

workspace.shared Workspace partajat cu un utilizator sau echipă
workspace.unshared Accesul la Workspace revocat

Sarcini

task.created Sarcină nouă creată
task.completed Sarcina marcată ca finalizată
task.overdue Sarcina a depășit data de scadență

Pachet și antet

Fiecare livrare urmează același șablon

Corp JSON predictibil, anteturi HTTP fixe, marcaj temporal ISO-8601 UTC.

Corpul cererii

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

Anteturi HTTP ale cererii

Antet Valoare exemplu Semnificație

Content-Type application/json Întotdeauna JSON, codificat în UTF-8

User-Agent PaperOffice-Webhook/1.0 Identificator fix pentru listele de permisiuni ale firewall-ului

X-PaperOffice-Event document.processed Tipul evenimentului livrat

X-PaperOffice-Event-ID a3b7f9c1… ID unic de 128 biți. Utilizați-l ca cheie de idempotență.

X-PaperOffice-Subscription-ID 42 ID-ul abonamentului care primește evenimentul

X-PaperOffice-Signature sha256=… HMAC-SHA256 al corpului brut, codat hexazecimal

cURL

1curl -X POST "https://api.paperoffice.ai/latest/webhooks/subscribe" \2  -H "Authorization: Bearer po_ut_YOUR_API_KEY" \3  -H "Content-Type: application/json" \4  -d '{5    "name": "My Production Webhook",6    "url": "https://yourdomain.com/webhooks/paperoffice",7    "events": ["document.processed", "job.completed", "job.failed"],8    "retry_policy": "exponential",9    "max_retries": 5,10    "timeout_ms": 1000011  }'

1import crypto from 'crypto';2import express from 'express';34const app = express();5const WEBHOOK_SECRET = process.env.PAPEROFFICE_WEBHOOK_SECRET;67app.post('/webhooks/paperoffice', express.raw({ type: 'application/json' }), (req, res) => {8  const signature = req.header('X-PaperOffice-Signature'); // "sha256=..."9  const eventId   = req.header('X-PaperOffice-Event-ID');10  const eventType = req.header('X-PaperOffice-Event');1112  const expected = 'sha256=' + crypto13    .createHmac('sha256', WEBHOOK_SECRET)14    .update(req.body)15    .digest('hex');1617  if (!signature || !crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {18    return res.status(401).send('invalid signature');19  }2021  const event = JSON.parse(req.body.toString());22  // store eventId as idempotency key -> never process the same ID twice23  console.log(eventType, event.data);24  res.status(200).send('ok');25});

1import hmac, hashlib, os2from flask import Flask, request, abort34app = Flask(__name__)5WEBHOOK_SECRET = os.environ["PAPEROFFICE_WEBHOOK_SECRET"]67@app.route("/webhooks/paperoffice", methods=["POST"])8def paperoffice_webhook():9    signature  = request.headers.get("X-PaperOffice-Signature", "")10    event_id   = request.headers.get("X-PaperOffice-Event-ID", "")11    event_type = request.headers.get("X-PaperOffice-Event", "")1213    expected = "sha256=" + hmac.new(14        WEBHOOK_SECRET.encode(),15        request.get_data(),16        hashlib.sha256,17    ).hexdigest()1819    if not hmac.compare_digest(signature, expected):20        abort(401)2122    payload = request.get_json()23    # store event_id as idempotency key in your DB24    print(event_type, payload["data"])25    return "ok", 200

1<?php2// PaperOffice webhook receiver with HMAC-SHA256 signature verification3$secret = getenv('PAPEROFFICE_WEBHOOK_SECRET');4$raw    = file_get_contents('php://input');56$signature  = $_SERVER['HTTP_X_PAPEROFFICE_SIGNATURE'] ?? '';7$event_id   = $_SERVER['HTTP_X_PAPEROFFICE_EVENT_ID'] ?? '';8$event_type = $_SERVER['HTTP_X_PAPEROFFICE_EVENT'] ?? '';910$expected = 'sha256=' . hash_hmac('sha256', $raw, $secret);11if (!hash_equals($expected, $signature)) {12    http_response_code(401);13    exit('invalid signature');14}1516$event = json_decode($raw, true);17// store event_id as idempotency key in your DB18error_log("{$event_type}: " . json_encode($event['data']));19http_response_code(200);20echo 'ok';

Verificarea semnăturii

Verificați fiecare livrare cu HMAC-SHA256

Calculați HMAC-SHA256 peste corpul brut al cererii folosind secretul dvs. comun și comparați rezultatul cu X-PaperOffice-Signature — obligatoriu cu timp de execuție constant.

Comparare în timp de execuție constant
hash_equals, hmac.compare_digest sau crypto.timingSafeEqual: Comparația nu trebuie să dezvăluie diferențe de timp de execuție.
Semnați corpul brut
Semnătura este valabilă pentru corpul request-ului nemodificat. Analizați JSON-ul doar după verificare, altfel hash-ul se va schimba.
Abonare prin API
POST /latest/webhooks/subscribe cu name, url și events. Dacă secret rămâne gol, PaperOffice îl generează și îl returnează o singură dată.

Autentificare & Chei Colecția Postman

Reîncercare și livrare

Trei strategii de reîncercare, până la 10 repetări

Alegeți politica pentru fiecare abonament. Fiecare încercare este logată cu codul de status, corpul răspunsului și măsurarea timpului.

Implicit exponential
Exponențial (implicit)

Intervalul dintre încercări se dublează după fiecare eșec.
linear
Liniar

Intervalul dintre încercări crește cu un pas fix.
none
Fără

Fără reîncercare, chiar și în cazul erorilor 5xx (trimite și uită). Util pentru hook-urile de testare.

Succes HTTP 2xx în interiorul ferestrei de timeout
Max. reîncercări Până la 10 reîncercări (implicit 5)
Timp de așteptare expirat 1.000–30.000 ms per încercare (standard 10.000). Prima încercare de livrare este limitată la 2 sau 5 secunde, în funcție de eveniment; repetările utilizează valoarea completă.
Jurnal de livrare Fiecare încercare este înregistrată; jurnalul rămâne disponibil chiar și după ștergerea abonamentului.

Gestionar-API

Cinci puncte finale sub /latest/webhooks/

Creare, listare, actualizare și ștergere a abonamentelor — inclusiv un punct final de test. Fiecare apel necesită un token Bearer.

POST /webhooks/subscribe Creare abonament; payload-urile sunt semnate cu HMAC-SHA256 Instrument MCPpo-webhooks-subscribe
GET /webhooks/list Listarea tuturor abonamentelor webhook ale contului Instrument MCPpo-webhooks-list
POST /webhooks/update Actualizarea URL-ului, evenimentelor, antetelor, politicii de reîncercare sau a stării active Instrument MCPpo-webhooks-update
POST /webhooks/delete Ștergeți abonamentul; jurnalul de livrare rămâne valabil Instrument MCPpo-webhooks-delete
POST /webhooks/test Trimiteți un eveniment de test către un abonament și verificați livrarea Instrument MCPpo-webhooks-test

Vizualizare server MCP Colecția Postman

Securitate

Consolidat de la bază

Șase mecanisme care intră în acțiune la fiecare livrare — din partea PaperOffice și din partea dumneavoastră.

HMAC-SHA256
Fiecare livrare este semnată cu secretul dumneavoastră. Compararea trebuie să se facă obligatoriu în timp constant.
Protecție SSRF
IP-urile private și interne, localhost și endpoint-urile de metadate cloud sunt blocate la abonare și la dispatch.
Sigur împotriva rebindării DNS
IP-ul este validat din nou la dispatch și blocat prin CURLOPT_RESOLVE.
HTTPS recomandat
Sunt acceptate http și https. Pentru mediul de producție, recomandăm HTTPS.
Idempotență prin ID-ul evenimentului
Fiecare livrare include un X-PaperOffice-Event-ID unic. Deduplicați din partea dumneavoastră.
Jurnal complet de livrare
Toate încercările sunt înregistrate: codul de status, corpul răspunsului, măsurarea timpului, mesajul de eroare.

Limite

Comportament de livrare configurabil per abonament

Toate valorile se seteză la creare sau ulterior prin /webhooks/update — per abonament, nu per cont.

0–10 Repetări per livrare (implicit 5)
1.000–30.000 ms Timp de așteptare per încercare (standard 10.000, prima încercare 2–5 s)
3 Politici de reîncercare: none, linear, exponential
HMAC-SHA256 Semnătură la fiecare livrare

Webhooks sunt disponibile începând cu planul Professional. Care plan se potrivește configurării dvs., arată prețurile.

Vizualizare prețuri Autentificare și chei

Întrebări

Întrebări frecvente despre webhooks

Cum verific o livrare?

Calculați HMAC-SHA256 peste corpul brut al cererii folosind secretul abonamentului dvs. și comparați rezultatul în timp constant cu antetul X-PaperOffice-Signature (format sha256=<hex>). Dacă semnătura nu corespunde, răspundeți cu HTTP 401 și nu procesați corpul.

De unde provine secretul?

La crearea abonamentului prin POST /latest/webhooks/subscribe. Lăsați câmpul secret gol, PaperOffice generează un secret și îl returnează o singură dată în răspuns. Prin POST /latest/webhooks/update îl puteți înlocui oricând.

Ce se întâmplă dacă endpoint-ul meu nu răspunde?

Răspunsuri în afara intervalului HTTP 2xx sau timeout-uri sunt considerate încercări eșuate. În funcție de politica de reîncercare (exponențială, liniară, niciuna), PaperOffice va repeta livrarea până la numărul setat de reîncercări (0–10, implicit 5). Fiecare încercare este înregistrată în jurnalul de livrare cu codul de status, răspunsul și măsurarea timpului.

Poate aceeași livrare să ajungă de două ori?

Da, acest lucru este posibil în cazul reîncercărilor după un timeout. Prin urmare, deduplicați folosind X-PaperOffice-Event-ID: ID-ul este unic pentru fiecare eveniment și poate fi folosit ca cheie de idempotență în baza de date.

Ce evenimente pot abona?

22 tipuri de evenimente din patru grupuri: Documente, Jobs, Workspace-uri și Sarcini. Puteți abona evenimente individuale sau toate cu ajutorul placeholder-ului *. Abonamentele pot fi restricționate suplimentar prin filtre (de exemplu, workspace_id sau pofid).

În ce plan sunt incluse webhooks?

Webhooks sunt disponibile începând cu planul Professional. Care plan se potrivește configurației dumneavoastră este indicat în tabelul de prețuri.

Cum ajung tabelele în webhook?

Pentru câmpurile de tip tabel (de exemplu, valorile de inspecție sau liniile de articol), document.processed transportă și data.extracted_tables. Lista sa tables conține o intrare pentru fiecare câmp de tabel cu key, label, columns și rows; fiecare celulă are value (un număr dacă PaperOffice a citit un număr, în caz contrar textul așa cum este tipărit) și value_raw (textul așa cum este tipărit, sau null dacă nu este cunoscut). extracted_fields rămâne neschimbat. Fiecare livrare conține cel mult 50 de tabele cu până la 1.000 de rânduri și 40 de coloane fiecare, 2.000 de caractere per celulă și 512 KB pentru toate tabelele împreună; dacă ceva este tăiat, truncated este true iar row_count indică numărul total de rânduri. Semnătura acoperă întregul corp al cererii, inclusiv extracted_tables.

Ce este nou în evenimentul document.processed?

Noutate: key_fields conține acum și document_number (de exemplu, numărul facturii) și publisher (emitentul documentului), dacă PaperOffice le-a citit. Elementele de linie ajung sub forma unui tabel în data.extracted_tables: tabelul cu key __document__content__extraction__line_items (pentru câmpurile agentului: _line_items) are un rând pentru fiecare element de linie.

Operațiuni și încredere

Ce verifică echipele enterprise înainte de primul apel

Contracte, securitate, suport și limite, toate link-urile într-un singur loc.

Următoarea stație

Iată cum continuăm

Următorul pas recomandat în funnel-ul dezvoltatorilor și două ramificații potrivite.

Postman CollectionImportare, testare, depanare în Postman Publishable KeysChei sigure în browser pentru artefacte AI și aplicații frontend Primul apel APIObțineți cheia, trimiteți cererea, verificați răspunsul

Înapoi la începutul pentru dezvoltatori

Evenimente în timp real. Semnate HMAC livrate.

22 tipuri de evenimente, grupate după entitate

Fiecare livrare urmează același șablon

Verificați fiecare livrare cu HMAC-SHA256

Trei strategii de reîncercare, până la 10 repetări

Exponențial (implicit)

Liniar

Fără

Cinci puncte finale sub /latest/webhooks/

Consolidat de la bază

Comportament de livrare configurabil per abonament

Întrebări frecvente despre webhooks

Ce verifică echipele enterprise înainte de primul apel

Iată cum continuăm

DMS on-premise pentru infrastructura dumneavoastră.

AI pentru industrie gata de utilizare în Claude & ChatGPT

Nu construiți niciodată singur.

Document Layer în loc de infrastructură.

Pentru partenerii care construiesc pe baza noastră.

Hardware propriu. Datacenter propriu.

31 de instrumente gratuite

PaperOffice PDF Reader