Naar inhoud springen
Overzicht Overzicht Nieuws Nieuws
Delen

Webhooks en gebeurtenissen

Realtime-events. HMAC-gesigneerd geleverd.

PaperOffice roept uw eindpunt aan zodra een document, taak, workspace of item verandert. Geen polling.

22 eventtypen, HMAC-SHA256-signatuur, drie retry-strategieën en een leveringslogboek per poging.

HMAC-SHA256 bij elke levering Tot 10 herhalingen (standaard 5) Idempotent per gebeurtenis-ID

Beschikbare gebeurtenissen

22 eventtypen, gegroepeerd per entiteit

Abonneer individuele events of gebruik de placeholder * voor alle.

Documenten

14
  • document.uploaded Nieuw document geüpload naar een workspace
  • document.created Alias voor document.uploaded (compatibiliteit)
  • document.processed OCR-/AI-IDP-pijplijn succesvol afgerond
  • document.edited Document bewerkt: metadata, tags of inhoud bijgewerkt
  • document.deleted Document naar de prullenbak verplaatst
  • document.restored Document hersteld uit de prullenbak
  • document.moved Document verplaatst tussen workspaces
  • document.version_created Nieuwe versie van een bestaand document
  • document.lifecycle_changed Bewaar-/archiefstatus gewijzigd
  • document.comment_added Opmerking bij een document gemaakt
  • document.note_added Interne notitie toegevoegd
  • document.tag_added Tag toegewezen aan een document
  • document.legal_hold_placed Legal Hold geactiveerd (onveranderlijk)
  • document.legal_hold_released Legal Hold opgeheven

Taken

3
  • job.completed Async-taak succesvol voltooid
  • job.failed Async-taak definitief mislukt
  • job.progress Voortgangsupdate bij langere taken

Workspaces

2
  • workspace.shared Werkruimte gedeeld met gebruiker of team
  • workspace.unshared Toegang tot werkruimte ingetrokken

Taken

3
  • task.created Nieuwe taak aangemaakt
  • task.completed Taak als voltooid gemarkeerd
  • task.overdue Taak heeft de einddatum overschreden

Payload en header

Elke levering volgt hetzelfde schema

Voorspelbare JSON-body, vaste HTTP-headers, ISO-8601-UTC-tijdstempel.

Aanvraagbody

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

Kop Voorbeeldwaarde Betekenis
Content-Type application/json Altijd JSON, UTF-8-gecodeerd
User-Agent PaperOffice-Webhook/1.0 Vaste identifier voor firewall-toegangslijsten
X-PaperOffice-Event document.processed Geleverd gebeurtenistype
X-PaperOffice-Event-ID a3b7f9c1… 128-bit-unieke ID. Gebruik deze als idempotentiesleutel.
X-PaperOffice-Subscription-ID 42 ID van het abonnement dat het event ontvangt
X-PaperOffice-Signature sha256=… HMAC-SHA256 van de ruwe body, hex-gecodeerd
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  }'

Handtekeningverificatie

Verifieer elke levering met HMAC-SHA256

Bereken HMAC-SHA256 over de ruwe request-body met uw gedeelde geheim en vergelijk het resultaat met X-PaperOffice-Signature — verplicht met constante looptijd.

  • Vergelijking in constante looptijd

    hash_equals, hmac.compare_digest of crypto.timingSafeEqual: De vergelijking mag geen tijdsverschillen onthullen.

  • Roh Body ondertekenen

    De handtekening geldt voor de ongewijzigde request-body. Parseer JSON pas na de verificatie, anders wijkt de hash af.

  • Abonneren via API

    POST /latest/webhooks/subscribe met name, url en events. Blijft secret leeg, dan genereert PaperOffice het en geeft het eenmalig terug.

Retry en levering

Drie retry-strategieën, tot 10 herhalingen

Kies het beleid per abonnement. Elke poging wordt gelogd met statuscode, response-body en timing.

  • Standaard exponential

    Exponentieel (standaard)

    De interval tussen pogingen verdubbelt zich na elke mislukte poging.

  • linear

    Lineair

    De interval tussen pogingen neemt toe met een vaste stap.

  • none

    Geen

    Geen herhaling, zelfs niet bij 5xx (send and forget). Handig voor test-hooks.

  • Succes HTTP 2xx binnen het time-outvenster
  • Max. herhalingen Tot 10 herhalingen (standaard 5)
  • Time-out 1.000–30.000 ms per poging (standaard 10.000)
  • Leveringslogboek Elke poging wordt gelogd; het logboek blijft behouden na het verwijderen van het abonnement.

Beheer-API

Vijf eindpunten onder /latest/webhooks/

Abonnementen aanmaken, opvragen, bijwerken en verwijderen — inclusief een test-eindpunt. Elke aanroep vereist een Bearer-token.

  • POST /webhooks/subscribe Abonnement aanmaken; payloads worden ondertekend met HMAC-SHA256 MCP-toolpo-webhooks-subscribe
  • GET /webhooks/list Alle webhook-abonnementen van de account opvragen MCP-toolpo-webhooks-list
  • POST /webhooks/update URL, gebeurtenissen, headers, retry-beleid of actieve status bijwerken MCP-toolpo-webhooks-update
  • POST /webhooks/delete Abonnement verwijderen; het bezorgprotocol blijft behouden MCP-toolpo-webhooks-delete
  • POST /webhooks/test Testevent naar een abonnement sturen en de bezorging controleren MCP-toolpo-webhooks-test

Beveiliging

Vanaf de grond versterkt

Zes mechanismen die bij elke bezorging actief zijn — aan de kant van PaperOffice en aan uw kant.

  • HMAC-SHA256

    Elke bezorging wordt ondertekend met uw geheim. De vergelijking moet uiterst constant in constante looptijd plaatsvinden.

  • SSRF-beveiliging

    Privé- en interne IP-adressen, localhost en cloud-metadata-eindpunten worden geblokkeerd bij het abonneren en dispatchen.

  • Veilig tegen DNS-rebinding

    Het IP-adres wordt opnieuw gevalideerd tijdens dispatchen en vastgezet via CURLOPT_RESOLVE.

  • HTTPS aanbevolen

    Zowel http als https worden geaccepteerd. Voor productieomgevingen raden we HTTPS aan.

  • Idempotentie via Event-ID

    Elke levering bevat een unieke X-PaperOffice-Event-ID. Voer deduplicatie uit aan uw kant.

  • Volledig leveringslogboek

    Alle pogingen worden gelogd: statuscode, response-body, timing en foutmelding.

Limieten

Levergedrag per abonnement configureerbaar

Stel alle waarden in bij het aanmaken of later via /webhooks/update — per abonnement, niet per account.

  • 0–10 Herhalingen per levering (standaard 5)
  • 1,000–30,000 ms Time-out per poging (standaard 10.000)
  • 3 Retry-beleiden: none, linear, exponential
  • HMAC-SHA256 Handtekening bij elke levering

Webhooks zijn beschikbaar vanaf het Professional plan. Welk plan bij uw setup past, ziet u in de prijsopgave.

Video

Webhooks in actie

Zie hoe PaperOffice webhooks in de praktijk werken — in de video.

Webhooks in actie

Vragen

Veelgestelde vragen over webhooks

Hoe verifieer ik een levering?

Bereken HMAC-SHA256 over de ruwe request-body met het geheim van uw abonnement en vergelijk het resultaat in constante tijd met de header X-PaperOffice-Signature (formaat sha256=<hex>). Als de handtekening niet overeenkomt, antwoord dan met HTTP 401 en verwerk de body niet.

Waar komt het geheim vandaan?

Bij het aanmaken van het abonnement via POST /latest/webhooks/subscribe. Laat het veld secret leeg, dan genereert PaperOffice een geheim en geeft dit eenmalig terug in de response. Via POST /latest/webhooks/update kunt u dit op elk moment vervangen.

Wat gebeurt er als mijn endpoint niet reageert?

Elk antwoord buiten HTTP 2xx of een time-out telt als een mislukte poging. Afhankelijk van het retry-beleid (exponentieel, lineair, geen) herhaalt PaperOffice de levering tot het ingestelde aantal herhalingen (0–10, standaard 5). Elke poging wordt in het leveringslogboek vastgelegd met statuscode, antwoord en timing.

Kan dezelfde levering twee keer aankomen?

Ja, bij herhalingen na een time-out is dat mogelijk. Dedupliceren daarom via X-PaperOffice-Event-ID: de ID is per event uniek en kan dienen als idempotentie-sleutel in uw database.

Welke events kan ik abonneren?

22 eventtypen uit vier groepen: documenten, jobs, workspaces en taken. U abonneert zich op individuele events of met de wildcard * op alle. Via filters (bijvoorbeeld workspace_id of pofid) kunt u een abonnement verder beperken.

In welk plan zijn webhooks inbegrepen?

Webhooks zijn beschikbaar vanaf het Professional-plan. Welk plan bij uw setup past, ziet u in de prijsopgave.

Waar wilt u PaperOffice testen?

Computer en smartphone zijn verbonden: workspace op de computer, vastleggen op de telefoon.

Uw proefversie is klaar

Waar wilt u beginnen?

De volledige workspace is geoptimaliseerd voor de computer. De mobiele versie is geschikt voor het vastleggen, controleren en goedkeuren van documenten.

app.paperoffice.ai

Start op de computer

We sturen uw persoonlijke toegangslink naar uw e-mailadres.

Gratis registreren App openen PaperOffice-app Het volledige product: web, desktop en mobiel. Documenten vastleggen, organiseren, zoeken en bewerken met het team. Gratis account vereist Playground openen Playground Probeer geselecteerde functies direct — zonder registratie, met een beperkte demo-API-sleutel. Wel een beperkte demo-API-sleutel