Hoppa till innehåll
Översikt Översikt Nyheter Nyheter
Dela

Webhooks & händelser

Realtidshändelser. Levereras med HMAC-signatur.

PaperOffice anropar din slutpunkt 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

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 laddats upp till en arbetsytan
  • 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 flyttat till papperskorgen
  • document.restored Dokument återställt från papperskorgen
  • document.moved Dokument flyttat mellan arbetsytor
  • 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 Arbetsyta delad med användare eller team
  • workspace.unshared Åtkomst till arbetsyta återkallad

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 ditt gemensamma hemlighet 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)
  • 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å din.

  • HMAC-SHA256

    Varje leverans signeras med ditt hemliga nyckel. 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

    IP-adressen valideras igen vid dispatch och låses fast med CURLOPT_RESOLVE.

  • 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å din sida.

  • 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)
  • 3 Retry-policys: none, linear, exponential
  • HMAC-SHA256 Signatur vid varje leverans

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

Video

Webhooks i aktion

Se hur PaperOffice webhooks fungerar i praktiken — i videon.

Webhooks i aktion

Frågor

Vanliga frågor om webhooks

Hur verifierar jag en leverans?

Beräkna HMAC-SHA256 över den råa request-bodyn med ditt abonnemangs 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 du ersätta den 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 din databas.

Vilka events kan jag prenumerera på?

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

I vilken plan ingår webhooks?

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

Var vill ni testa PaperOffice?

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

Din provperiod är redo

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.

app.paperoffice.ai

Börja på datorn

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

Registrera gratis Öppna appen PaperOffice-appen Hela produkten: webb, dator och mobil. Fånga, organisera, sök och arbeta med dokument tillsammans med teamet. Gratis konto krävs Öppna Playground Playground Prova utvalda funktioner direkt — utan registrering, med en begränsad demo-API-nyckel. En begränsad demo-API-nyckel