Hoppa till innehåll
Frågor?PaperOffice AI Phone Agent 24/7+49 69 3487102-0
Academy Kontakt Översikt Översikt Nyheter Nyheter
Dela

Webhooks & händelser

Realtidshändelser. Levereras med HMAC-signatur.

PaperOffice anropar den egna slutpunkten så snart ett dokument, jobb, arbetsyta eller uppgift ändras. Ingen pollning.

22 händelsetyper, HMAC-SHA256-signatur, tre återförsöksstrategier och en leveranslogg per försök.

HMAC-SHA256 vid varje leverans Upp till 10 upprepningar (standard 5) Idempotent per event-ID
Realtidshändelser. Levereras med HMAC-signatur.

Tillgängliga event

22 eventtyper, grupperade efter entitet

Prenumerera på enskilda events eller använd platshållaren * för alla.

Dokument

14
  • document.uploaded Nytt dokument laddas upp till en Workspace
  • document.created Alias för document.uploaded (kompatibilitet)
  • document.processed OCR-/AI-IDP-pipeline slutförd med framgång
  • document.edited Dokument redigerat: metadata, taggar eller innehåll uppdaterat
  • document.deleted Dokument raderat; delete_mode visar trash (papperskorg i Business och Compliance) eller instant (slutgiltigt i standard)
  • document.restored Dokument återställt från papperskorgen (Business och Compliance)
  • document.moved Dokument flyttas mellan Workspaces
  • document.version_created Ny version av ett befintligt dokument
  • document.lifecycle_changed Bevarande-/arkiveringsstatus ändrad
  • document.comment_added Kommentar till ett dokument skapad
  • document.note_added Intern anteckning bifogad
  • document.tag_added Tag tilldelad ett dokument
  • document.legal_hold_placed Legal Hold aktiverad (oföränderlig)
  • document.legal_hold_released Legal Hold upphävd

Jobb

3
  • job.completed Asynkront jobb slutfört med framgång
  • job.failed Asynkront jobb misslyckades definitivt
  • job.progress Framstegsuppdatering för längre jobb

Workspaces

2
  • workspace.shared Workspace delas med en användare eller grupp
  • workspace.unshared Workspace behörighet återkallas

Uppgifter

3
  • task.created Ny uppgift skapad
  • task.completed Uppgift markerad som klar
  • task.overdue Uppgift har passerat sitt förfallodatum

Payload och rubrik

Varje leverans följer samma schema

Förutsägbar JSON-body, fasta HTTP-huvuden, ISO-8601-UTC-tidsstämpel.

Begäransbody

{
  "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-begäranshuvud

Huvud Exempelvärde Betydelse
Content-Type application/json Alltid JSON, UTF-8-kodad
User-Agent PaperOffice-Webhook/1.0 Fast identifier för brandväggs-tillåtna listor
X-PaperOffice-Event document.processed Levererad eventtyp
X-PaperOffice-Event-ID a3b7f9c1… 128-bit unik ID. Använd den som idempotensnyckel.
X-PaperOffice-Subscription-ID 42 ID för prenumerationen som tar emot händelsen
X-PaperOffice-Signature sha256=… HMAC-SHA256 av den råa kroppen, hex-kodad
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  }'

Signaturverifiering

Verifiera varje leverans med HMAC-SHA256

Beräkna HMAC-SHA256 över den råa begärskroppen med den gemensamma hemligheten och jämför resultatet med X-PaperOffice-Signature — obligatoriskt med konstant exekveringstid.

  • Jämförelse med konstant exekveringstid

    hash_equals, hmac.compare_digest eller crypto.timingSafeEqual: Jämförelsen får inte avslöja exekveringstidskillnader.

  • Signera roher kropp

    Signaturen gäller för oförändrad begärans kropp. Parsa inte JSON förrän efter verifiering, annars blir hashen felaktig.

  • Prenumerera via API

    POST /latest/webhooks/subscribe med namn, url och händelser. Om secret lämnas tom genererar PaperOffice det och returnerar det en gång.

Försök igen och leverans

Tre retry-strategier, upp till 10 försök

Välj policy per prenumeration. Varje försök loggas med statuskod, svarskropp och tidtagning.

  • Default exponential

    Exponentiell (standard)

    Avståndet mellan försöken fördubblas efter varje misslyckat försök.

  • linear

    Linjär

    Avståndet mellan försöken ökar med ett fast steg.

  • none

    Ingen

    Ingen återförsök, även inte vid 5xx (skicka och glöm). Användbart för test-hooks.

  • Framgång HTTP 2xx inom timeout-fönstret
  • Max återförsök Upp till 10 återförsök (standard 5)
  • Tidsgräns 1 000–30 000 ms per försök (standard 10 000). Det första leveransförsöket är begränsat till antingen 2 eller 5 sekunder beroende på händelsen, medan upprepningar använder hela värdet.
  • Leveranslogg Varje försök loggas; loggen behålls även efter att prenumerationen har raderats.

Hanterings-API

Fem slutpunkter under /latest/webhooks/

Skapa, lista, uppdatera och ta bort prenumerationer — inklusive en testslutpunkt. Varje anrop använder ett Bearer-token.

  • POST /webhooks/subscribe Skapa prenumeration; payloads signeras med HMAC-SHA256 MCP-verktygpo-webhooks-subscribe
  • GET /webhooks/list Lista alla webhook-prenumerationer för kontot MCP-verktygpo-webhooks-list
  • POST /webhooks/update Uppdatera URL, händelser, rubriker, retry-policy eller aktiv status MCP-verktygpo-webhooks-update
  • POST /webhooks/delete Avsluta prenumeration; leveransprotokollet behålls MCP-verktygpo-webhooks-delete
  • POST /webhooks/test Skicka testhändelse till en prenumeration och verifiera leveransen MCP-verktygpo-webhooks-test

Säkerhet

Hårdnad från grunden

Sex mekanismer som aktiveras vid varje leverans — på PaperOffices sida och på mottagarens.

  • HMAC-SHA256

    Varje leverans signeras med den hemliga nyckeln. Jämförelsen måste alltid ske i konstant tid.

  • SSRF-skydd

    Privata och interna IP-adresser, localhost och molnmetadata-slutpunkter blockeras vid prenumeration och dispatch.

  • DNS-rebinding-säker

    Måladressen kontrolleras igen vid leveranstillfället.

  • HTTPS rekommenderas

    Både http och https accepteras. För produktionsdrift rekommenderar vi HTTPS.

  • Idempotens via event-ID

    Varje leverans innehåller en unik X-PaperOffice-Event-ID. Deduplicera på mottagarsidan.

  • Fullständigt leveransprotokoll

    Alla försök loggas: statuskod, response-body, tidmätning, felmeddelande.

Gränser

Leveransbeteende kan konfigureras per prenumeration

Alla värden anges vid skapande eller senare via /webhooks/update — per prenumeration, inte per konto.

  • 0–10 Upprepningar per leverans (standard 5)
  • 1 000–30 000 ms Timeout per försök (standard 10 000, första försöket 2–5 s)
  • 3 Retry-policys: none, linear, exponential
  • HMAC-SHA256 Signatur vid varje leverans

Webhooks är tillgängliga från planen Professional. Vilken plan som passar konfigurationen visas i prisöversikten.

Frågor

Vanliga frågor om webhooks

Hur verifierar jag en leverans?

Beräkna HMAC-SHA256 över den råa request-bodyn med abonnemangets hemlighet och jämför resultatet i konstant tid med huvudet X-PaperOffice-Signature (format sha256=<hex>). Om signaturen inte stämmer, svara med HTTP 401 och bearbeta inte bodyn.

Varifrån kommer hemligheten?

Vid skapandet av abonnemanget via POST /latest/webhooks/subscribe. Lämna fältet secret tomt, så genererar PaperOffice en hemlighet och returnerar den en gång i svaret. Via POST /latest/webhooks/update kan den ersättas när som helst.

Vad händer om min slutpunkt inte svarar?

Varje svar utanför HTTP 2xx eller ett timeout räknas som ett misslyckat försök. Beroende på retry-policy (exponential, linear, none) upprepar PaperOffice leveransen upp till det inställda antalet återförsök (0–10, standard 5). Varje försök loggas med statuskod, svar och tidtagning i leveransloggen.

Kan samma leverans komma två gånger?

Ja, vid återförsök efter ett timeout är det möjligt. Deduplicera därför via X-PaperOffice-Event-ID: ID:t är unikt per event och lämpar sig som idempotensnyckel i den egna databasen.

Vilka events kan jag prenumerera på?

22 eventtyper från fyra grupper: dokument, jobb, arbetsytor och uppgifter. Prenumeration sker på enskilda events eller med jokertecknet * på alla. Med filters (t.ex. workspace_id eller pofid) kan en prenumeration begränsas ytterligare.

I vilken plan ingår webhooks?

Webhooks finns tillgängliga från och med planen Professional. Vilken plan som passar konfigurationen visas i prisöversikten.

Hur levereras tabeller via webhook?

För tabellfält (till exempel inspektionsvärden eller radposter) innehåller document.processed även data.extracted_tables. Dess lista tables innehåller ett objekt per tabellfält med key, label, columns och rows; varje cell har value (ett tal om PaperOffice läste ett tal, annars texten som den trycktes) och value_raw (texten som den trycktes, eller null om det inte är känt). extracted_fields förblir oförändrad. Varje leverans innehåller högst 50 tabeller med upp till 1 000 rader och 40 kolumner vardera, 2 000 tecken per cell och 512 KB för alla tabeller tillsammans; om något klipps bort är truncated true och row_count anger det fulla antalet rader. Signaturen täcker hela begäransbodyn, inklusive extracted_tables.

Vad är nytt i händelsen document.processed?

Nytt: key_fields innehåller nu även document_number (till exempel fakturanumret) och publisher (dokumentets utfärdare), om PaperOffice har läst in dem. Radposter levereras som en tabell i data.extracted_tables: tabellen med key __document__content__extraction__line_items (för agentfält: _line_items) har en rad per radpost.

PaperOffice AI · Problem Solver

Berätta för oss, vad som kostar tid varje dag.

Beskriv enkelt. Inga facktermer behövs.

Eller starta med ett exempel

Hur ska PaperOffice användas?

Dator och smartphone är anslutna: Arbetsyta på datorn, registrering på telefonen.

Var vill du börja?

Den fullständiga arbetsytan är optimerad för datorn. Mobilversionen passar bra för att registrera, granska och godkänna dokument.

Registrera gratis app.paperoffice.ai

Börja på datorn

Vi skickar din personliga åtkomstlänk till din e-postadress.