Webhooks & Events

Real-time events. Delivered HMAC-signed.

PaperOffice calls your endpoint as soon as a document, job, workspace or task changes. No polling.

22 event types, HMAC-SHA256 signatures, three retry strategies and a delivery log for every attempt.

Subscribe to the first webhook Start the first API call

HMAC-SHA256 on every delivery Up to 10 retries (default 5) Idempotent via event ID

Real-time events. Delivered HMAC-signed.

Own EU infrastructure Your data remains in Europe.
ISO/IEC 27001 certified Certificate on request under NDA.
SOC 2 Type II in preparation International audit standards.
24+ years of experience Proven. Stable. Future-proof.

Available events

22 event types, grouped by entity

Subscribe to individual events or use the wildcard * for everything.

Documents

document.uploaded New document uploaded to a workspace
document.created Alias for document.uploaded (compatibility)
document.processed OCR/AI-IDP pipeline finished successfully
document.edited Document edited: metadata, tags or content updated
document.deleted Document deleted; delete_mode shows trash (recycle bin in Business and Compliance) or instant (permanent in Standard)
document.restored Document recovered from trash (Business and Compliance)
document.moved Document moved between workspaces
document.version_created New version added to an existing document
document.lifecycle_changed Retention / archival status changed
document.comment_added Comment posted on a document
document.note_added Internal note attached
document.tag_added Tag assigned to a document
document.legal_hold_placed Legal hold activated (immutable)
document.legal_hold_released Legal hold released

Jobs

job.completed Async job finished successfully
job.failed Async job failed terminally
job.progress Progress update during long-running jobs

Workspaces

workspace.shared Workspace shared with a user or team
workspace.unshared Workspace access revoked

Tasks

task.created New task created
task.completed Task marked as complete
task.overdue Task passed its due date

Payload and headers

Every delivery follows the same schema

Predictable JSON body, fixed HTTP headers, ISO-8601 UTC timestamps.

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 headers

Header Example value Meaning

Content-Type application/json Always JSON, UTF-8 encoded

User-Agent PaperOffice-Webhook/1.0 Fixed identifier for firewall allowlists

X-PaperOffice-Event document.processed Event type being delivered

X-PaperOffice-Event-ID a3b7f9c1… 128-bit unique ID. Use it as your idempotency key.

X-PaperOffice-Subscription-ID 42 ID of the subscription receiving the event

X-PaperOffice-Signature sha256=… HMAC-SHA256 of the raw body, hex-encoded

cURL

1curl -X POST "https://api.paperoffice.ai/latest/webhooks/subscribe" \2  -H "Authorization: Bearer po_ut_YOUR_API_KEY" \3  -H "Content-Type: application/json" \4  -d '{5    "name": "My Production Webhook",6    "url": "https://yourdomain.com/webhooks/paperoffice",7    "events": ["document.processed", "job.completed", "job.failed"],8    "retry_policy": "exponential",9    "max_retries": 5,10    "timeout_ms": 1000011  }'

1import crypto from 'crypto';2import express from 'express';34const app = express();5const WEBHOOK_SECRET = process.env.PAPEROFFICE_WEBHOOK_SECRET;67app.post('/webhooks/paperoffice', express.raw({ type: 'application/json' }), (req, res) => {8  const signature = req.header('X-PaperOffice-Signature'); // "sha256=..."9  const eventId   = req.header('X-PaperOffice-Event-ID');10  const eventType = req.header('X-PaperOffice-Event');1112  const expected = 'sha256=' + crypto13    .createHmac('sha256', WEBHOOK_SECRET)14    .update(req.body)15    .digest('hex');1617  if (!signature || !crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {18    return res.status(401).send('invalid signature');19  }2021  const event = JSON.parse(req.body.toString());22  // store eventId as idempotency key -> never process the same ID twice23  console.log(eventType, event.data);24  res.status(200).send('ok');25});

1import hmac, hashlib, os2from flask import Flask, request, abort34app = Flask(__name__)5WEBHOOK_SECRET = os.environ["PAPEROFFICE_WEBHOOK_SECRET"]67@app.route("/webhooks/paperoffice", methods=["POST"])8def paperoffice_webhook():9    signature  = request.headers.get("X-PaperOffice-Signature", "")10    event_id   = request.headers.get("X-PaperOffice-Event-ID", "")11    event_type = request.headers.get("X-PaperOffice-Event", "")1213    expected = "sha256=" + hmac.new(14        WEBHOOK_SECRET.encode(),15        request.get_data(),16        hashlib.sha256,17    ).hexdigest()1819    if not hmac.compare_digest(signature, expected):20        abort(401)2122    payload = request.get_json()23    # store event_id as idempotency key in your DB24    print(event_type, payload["data"])25    return "ok", 200

1<?php2// PaperOffice webhook receiver with HMAC-SHA256 signature verification3$secret = getenv('PAPEROFFICE_WEBHOOK_SECRET');4$raw    = file_get_contents('php://input');56$signature  = $_SERVER['HTTP_X_PAPEROFFICE_SIGNATURE'] ?? '';7$event_id   = $_SERVER['HTTP_X_PAPEROFFICE_EVENT_ID'] ?? '';8$event_type = $_SERVER['HTTP_X_PAPEROFFICE_EVENT'] ?? '';910$expected = 'sha256=' . hash_hmac('sha256', $raw, $secret);11if (!hash_equals($expected, $signature)) {12    http_response_code(401);13    exit('invalid signature');14}1516$event = json_decode($raw, true);17// store event_id as idempotency key in your DB18error_log("{$event_type}: " . json_encode($event['data']));19http_response_code(200);20echo 'ok';

Signature verification

Verify every delivery with HMAC-SHA256

Compute HMAC-SHA256 over the raw request body using your shared secret and compare the result against X-PaperOffice-Signature — always with a constant-time comparison.

Constant-time comparison
hash_equals, hmac.compare_digest or crypto.timingSafeEqual: the comparison must not leak timing differences.
Sign the raw body
The signature covers the unmodified request body. Parse JSON only after the check, otherwise the hash will differ.
Subscribe via the API
POST /latest/webhooks/subscribe with name, url and events. Leave secret empty and PaperOffice generates it and returns it once.

Authentication & keys Postman collection

Retry and delivery

Three retry strategies, up to 10 retries

Pick a policy per subscription. Every attempt is logged with status code, response body and timing.

Default exponential
Exponential (default)

The gap between attempts doubles after every failed attempt.
linear
Linear

The gap between attempts grows by a fixed step.
none
None

Fire-and-forget. No retry, not even on 5xx. Useful for test hooks.

Success HTTP 2xx within your timeout window
Max retries Up to 10 retries (default 5)
Timeout 1,000–30,000 ms per attempt (default 10,000). Depending on the event, the first delivery attempt is capped at 2 or 5 seconds; retries use the full value.
Delivery log Every attempt is logged; the log is kept even after the subscription is deleted.

Management API

Five endpoints under /latest/webhooks/

Create, list, update and delete subscriptions — plus a test endpoint. Every call carries a bearer token.

POST /webhooks/subscribe Create a subscription; payloads are signed with HMAC-SHA256 MCP toolpo-webhooks-subscribe
GET /webhooks/list List all webhook subscriptions of the account MCP toolpo-webhooks-list
POST /webhooks/update Update URL, events, headers, retry policy or the active flag MCP toolpo-webhooks-update
POST /webhooks/delete Delete a subscription; the delivery log is preserved MCP toolpo-webhooks-delete
POST /webhooks/test Send a test event to a subscription to verify delivery MCP toolpo-webhooks-test

See the MCP server Postman collection

Security

Hardened by design

Six mechanisms that take effect on every delivery — on the PaperOffice side and on yours.

HMAC-SHA256
Every delivery is signed with your secret. The comparison must run in constant time.
SSRF protection
Private and internal IPs, localhost and cloud metadata endpoints are blocked at subscribe and dispatch time.
DNS rebinding safe
The target address is checked again at delivery time.
HTTPS recommended
http and https are accepted. We recommend HTTPS for production.
Idempotency via event ID
Every delivery carries a unique X-PaperOffice-Event-ID. Deduplicate on your side.
Full delivery log
All attempts are logged: status code, response body, timing, error message.

Limits

Delivery behavior is configurable per subscription

You set every value when creating the subscription or later via /webhooks/update — per subscription, not per account.

0–10 Retries per delivery (default 5)
1,000–30,000 ms Timeout per attempt (default 10,000, first attempt 2–5 s)
3 Retry policies: none, linear, exponential
HMAC-SHA256 Signature on every delivery

Webhooks are available from the Professional plan upwards. The pricing overview shows which plan fits your setup.

See pricing Authentication & keys

Questions

Common questions about webhooks

How do I verify a delivery?

Compute HMAC-SHA256 over the raw request body with your subscription secret and compare the result in constant time against the X-PaperOffice-Signature header (format sha256=<hex>). If the signature does not match, answer with HTTP 401 and do not process the body.

Where does the secret come from?

From creating the subscription via POST /latest/webhooks/subscribe. Leave the secret field empty and PaperOffice generates one and returns it once in the response. You can replace it at any time via POST /latest/webhooks/update.

What happens when my endpoint does not respond?

Any response outside HTTP 2xx or a timeout counts as a failed attempt. Depending on the retry policy (exponential, linear, none), PaperOffice repeats the delivery up to the configured number of retries (0–10, default 5). Every attempt is recorded in the delivery log with status code, response and timing.

Can the same delivery arrive twice?

Yes, this is possible when a delivery is retried after a timeout. Deduplicate via X-PaperOffice-Event-ID: the ID is unique per event and serves as the idempotency key in your database.

Which events can I subscribe to?

22 event types in four groups: documents, jobs, workspaces and tasks. You subscribe to individual events or to all of them with the wildcard *. With filters (such as workspace_id or pofid) you narrow a subscription down further.

Which plan includes webhooks?

Webhooks are available from the Professional plan upwards. The pricing overview shows which plan fits your setup.

Operations and trust

What enterprise teams check before the first call

Contracts, security, support and limits, all linked in one place.

Next station

Where to go next

The recommended next step in the developer funnel and two fitting branches.

Postman CollectionImport, test, debug in Postman Publishable KeysBrowser-safe keys for AI artifacts and frontend apps First API callGet a key, send a request, inspect the response

Back to the developer start

Real-time events. Delivered HMAC-signed.

22 event types, grouped by entity

Every delivery follows the same schema

Verify every delivery with HMAC-SHA256

Three retry strategies, up to 10 retries

Exponential (default)

Linear

None

Five endpoints under /latest/webhooks/

Hardened by design

Delivery behavior is configurable per subscription

Common questions about webhooks

What enterprise teams check before the first call

Where to go next

On-premise DMS for your infrastructure.

Industry AI ready in Claude & ChatGPT

Never build alone.

Document Layer, not infrastructure.

For partners who build on top.

Own hardware. Own datacenter.

31 free tools