Sari la conținut
Prezentare Prezentare Noutăți Noutăți
Distribuie

Webhooks și Evenimente

Evenimente în timp real. Semnate HMAC livrate.

PaperOffice apelează endpoint-ul dvs. imediat ce se modifică un document, job, spațiu de lucru sau sarcină. Fără polling.

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

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

Evenimente disponibile

22 tipuri de evenimente, grupate după entitate

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

Documente

14
  • document.uploaded Document nou încărcat într-un spațiu de lucru
  • 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 mutat la coșul de gunoi
  • document.restored Document restaurat din coșul de gunoi
  • document.moved Document mutat între spații de lucru
  • 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

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

Workspaces

2
  • workspace.shared Spațiu de lucru partajat cu un utilizator sau echipă
  • workspace.unshared Accesul la spațiul de lucru a fost revocat

Sarcini

3
  • 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
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  }'

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ă.

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 pe încercare (standard 10.000)
  • 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

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,0–30,0 ms Timeout per încercare (implicit 10.000)
  • 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.

Video

Webhooks în acțiune

Vedeți cum funcționează webhooks PaperOffice în practică — în video.

Webhooks în acțiune

Î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.

Unde doriți să testați PaperOffice?

Calculatorul și smartphone-ul sunt conectate: spațiu de lucru pe calculator, captură pe telefon.

Versiunea dvs. de test este pregătită

Unde doriți să începeți?

Spațiul de lucru complet este optimizat pentru calculator. Versiunea mobilă este potrivită pentru capturarea, verificarea și aprobarea documentelor.

app.paperoffice.ai

Începeți pe calculator

Vă vom trimite link-ul personal de acces la adresa dvs. de e-mail.

Înregistrare gratuită Deschideți aplicația Aplicația PaperOffice Produsul complet: web, desktop și mobil. Capturați, organizați, căutați și lucrați pe documente împreună cu echipa. Este necesar un cont gratuit Deschideți Playground Playground Încercați funcții selectate imediat — fără înregistrare, cu o cheie API demo restricționată. Fără înregistrare, dar cu o cheie API demo restricționată