Spring til indhold
Oversigt Oversigt Nyheder Nyheder
Del

Webhooks og begivenheder

Realtime-hændelser. Leveret med HMAC-signatur.

PaperOffice kalder dit slutpunkt, så snart et dokument, job, workspace eller opgave ændres. Ingen polling.

22 hændelsestyper, HMAC-SHA256-signatur, tre retry-strategier og en leveringslog pr. forsøg.

HMAC-SHA256 ved hver leverance Op til 10 gentagelser (standard 5) Idempotent per event-ID

Tilgængelige events

22 eventtyper, grupperet efter enhed

Abonner på enkelte events, eller brug pladsholderen * til alle.

Dokumenter

14
  • document.uploaded Nyt dokument uploadet til en workspace
  • document.created Alias for document.uploaded (kompatibilitet)
  • document.processed OCR-/AI-IDP-pipeline fuldført med succes
  • document.edited Dokument redigeret: metadata, tags eller indhold opdateret
  • document.deleted Dokument flyttet til papirkurven
  • document.restored Dokument gendannet fra papirkurven
  • document.moved Dokument flyttet mellem workspaces
  • document.version_created Ny version af et eksisterende dokument
  • document.lifecycle_changed Opbevarings-/arkiveringsstatus ændret
  • document.comment_added Kommentar til et dokument oprettet
  • document.note_added Intern note vedhæftet
  • document.tag_added Et tag tildelt et dokument
  • document.legal_hold_placed Legal Hold aktiveret (uforanderlig)
  • document.legal_hold_released Legal Hold ophævet

Job

3
  • job.completed Asynkront job afsluttet med succes
  • job.failed Asynkront job endeligt mislykket
  • job.progress Fremdrapportering ved længere jobs

Workspaces

2
  • workspace.shared Arbejdsområde delt med bruger eller team
  • workspace.unshared Adgang til arbejdsområde trukket tilbage

Opgaver

3
  • task.created Ny opgave oprettet
  • task.completed Opgave markeret som afsluttet
  • task.overdue Opgave har overskredet sin udløbsdato

Payload og header

Hver levering følger det samme skema

Forudsigelig JSON-body, faste HTTP-header, ISO-8601-UTC-tidsstempel.

Request-body

{
  "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-request-header

Overskrift Eksempelværdi Betydning
Content-Type application/json Altid JSON, UTF-8-kodet
User-Agent PaperOffice-Webhook/1.0 Fast identifikator til firewall-allowlists
X-PaperOffice-Event document.processed Leveret event-type
X-PaperOffice-Event-ID a3b7f9c1… 128-bit unik ID. Brug den som idempotensnøgle.
X-PaperOffice-Subscription-ID 42 Abonnements-ID, der modtager begivenheden
X-PaperOffice-Signature sha256=… HMAC-SHA256 af den rå body, hex-kodet
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  }'

Signaturverifikation

Verificer hver levering med HMAC-SHA256

Beregn HMAC-SHA256 over den rå request-body med dit fælles hemmelige nøgle og sammenlign resultatet med X-PaperOffice-Signature — strengt med konstant køretid.

  • Sammenligning i konstant køretid

    hash_equals, hmac.compare_digest eller crypto.timingSafeEqual: Sammenligningen må ikke afsløre køretidsforskelle.

  • Rohen Body signere

    Signaturen gælder for den uændrede request-body. Pars JSON først efter verificeringen, da hash'en ellers vil afvige.

  • Abonnér via API

    POST /latest/webhooks/subscribe med name, url og events. Hvis secret er tomt, genererer PaperOffice det og returnerer det én gang.

Retry og levering

Tre retry-strategier, op til 10 gentagelser

Vælg policy pr. abonnement. Hvert forsøg logges med statuskode, response-body og timing.

  • Default exponential

    Eksponentiel (standard)

    Afstanden mellem forsøg fordobles efter hvert mislykket forsøg.

  • linear

    Lineær

    Afstanden mellem forsøg øges med et fast trin.

  • none

    Ingen

    Ingen gentagelse, heller ikke ved 5xx (send og glem). Brugeligt til test-hooks.

  • Succes HTTP 2xx inden for timeout-vinduet
  • Maks. gentagelser Op til 10 gentagelser (standard 5)
  • Tidsudløb 1.000–30.000 ms pr. forsøg (standard 10.000)
  • Leveringslog Hvert forsøg logges; loggen bevares selv efter sletning af abonnementet.

Ledelse-API

Fem endpoints under /latest/webhooks/

Opret, vis, opdater og slet abonnementer — samt et test-endpoint. Hvert kald kræver et Bearer-token.

  • POST /webhooks/subscribe Opret abonnement; payloads signeres med HMAC-SHA256 MCP-værktøjpo-webhooks-subscribe
  • GET /webhooks/list Vis alle webhook-abonnementer for kontoen MCP-værktøjpo-webhooks-list
  • POST /webhooks/update Opdater URL, events, headers, retry-policy eller aktiv status MCP-værktøjpo-webhooks-update
  • POST /webhooks/delete Slet abonnement; leveringsprotokoll bevares MCP-værktøjpo-webhooks-delete
  • POST /webhooks/test Send test-event til et abonnement og verificer levering MCP-værktøjpo-webhooks-test

Sikkerhed

Hårdnet fra bunden af

Seks mekanismer, der aktiveres ved hver levering — på PaperOffice's side og hos dig.

  • HMAC-SHA256

    Hver levering signeres med dit secret. Sammenligningen skal udføres i konstant tid.

  • SSRF-beskyttelse

    Private og interne IP-adresser, localhost og cloud-metadata-endpoints blokeres ved abonnement og dispatch.

  • Sikker mod DNS-rebinding

    IP-adressen valideres igen ved dispatch og fastlåses via CURLOPT_RESOLVE.

  • HTTPS anbefales

    Både http og https accepteres. Til produktionsbrug anbefaler vi HTTPS.

  • Idempotens via event-ID

    Hver levering indeholder en unik X-PaperOffice-event-ID. Udfør deduplikering på din side.

  • Fuldt leveringslog

    Alle forsøg logges: statuskode, response-body, timing og fejlmeddelelse.

Begrænsninger

Leveringsadfærd kan konfigureres pr. abonnement

Alle værdier indstilles ved oprettelse eller senere via /webhooks/update — pr. abonnement, ikke pr. konto.

  • 0–10 Gentagelser pr. levering (standard 5)
  • 1,000–30,000 ms Timeout pr. forsøg (standard 10.000)
  • 3 Retry-policys: none, linear, exponential
  • HMAC-SHA256 Signatur ved hver levering

Webhooks er tilgængelige fra planen Professional. Hvilken plan der passer til dit setup, vises i prisoversigten.

Video

Webhooks i aktion

Se, hvordan PaperOffice webhooks fungerer i praksis — i videoen.

Webhooks i aktion

Spørgsmål

Ofte stillede spørgsmål om webhooks

Hvordan verificerer jeg en levering?

Beregn HMAC-SHA256 over den rå request-body med dit abonnementets hemmelighed og sammenlign resultatet i konstant tid med headeren X-PaperOffice-Signature (format sha256=<hex>). Hvis signaturen ikke matcher, skal du svare med HTTP 401 og ikke behandle body.

Hvor kommer hemmeligheden fra?

Ved oprettelse af abonnementet via POST /latest/webhooks/subscribe. Hvis du efterlader feltet secret tomt, genererer PaperOffice en hemmelighed og returnerer den én gang i svaret. Via POST /latest/webhooks/update kan du erstatte den til enhver tid.

Hvad sker der, hvis min endpoint ikke svarer?

Ethvert svar uden for HTTP 2xx eller en timeout tæller som et mislykket forsøg. Afhængigt af retry-policy (exponential, linear, none) gentager PaperOffice leveringen op til det indstillede antal gentagelser (0–10, standard 5). Hvert forsøg logges med statuskode, svar og tidsmåling i leveringsloggen.

Kan den samme levering ankomme to gange?

Ja, det er muligt ved gentagelser efter en timeout. Deduplicér derfor via X-PaperOffice-Event-ID: ID'et er unikt pr. event og egner sig som idempotensnøgle i din database.

Hvilke events kan jeg abonnere på?

22 eventtyper fra fire grupper: dokumenter, jobs, workspaces og opgaver. Du kan abonnere på enkelte events eller alle med pladsholderen *. Du kan begrænse et abonnement yderligere ved hjælp af filtre (f.eks. workspace_id eller pofid).

Hvilken plan indeholder webhooks?

Webhooks er tilgængelige fra planen Professional. Pristabellen viser, hvilken plan der passer til dit setup.

Hvor vil I prøve PaperOffice?

Computer og smartphone er forbundet: Workspace på computeren, indfangning på telefonen.

Din prøveversion er klar

Hvor vil du starte?

Den fulde workspace er optimeret til computeren. Den mobile version er velegnet til at indfange, kontrollere og godkende dokumenter.

app.paperoffice.ai

Start på computeren

Vi sender dit personlige adgangslinke til din e-mailadresse.

Åbn PaperOffice Mobile

Indfange og rediger dokumenter direkte med smartphonen.

Åbn mobilversion
Registrere gratis Åbn app PaperOffice-app Det fulde produkt: web, desktop og mobil. Registrér, organisér, søg og arbejd med dokumenter sammen med teamet. Gratis konto påkrævet Åbn Playground Playground Prøv udvalgte funktioner med det samme — uden registrering, med en begrænset demo-API-nøgle. En begrænset demo-API-nøgle