Webhook contract

The exact HTTP shape, signing scheme, response codes, retry policy, and idempotency rules for webhooks sent from your platform to Paperless.

Endpoint

POST https://api.paperless.example/webhooks/{provider}
Content-Type: application/json
X-Paperless-Signature: <hex-encoded HMAC-SHA256>
X-Paperless-Timestamp: <unix seconds>

{provider} is the short slug Paperless assigns to your platform on onboarding (lowercase, alphanumeric + dashes; e.g. acme).

Request headers

Request body

Every event uses the same envelope:

{
  "external_event_id": "evt_acme_8f3e1c9a-2c11-4c1b-9c3c-c5e1c0f1abc1",
  "event_type":        "order.completed",
  "created_at":        "2026-05-15T17:21:19Z",
  "merchant_id":       "MERCHANT_12345",
  "location_id":       "LOC_001",
  "data": {
    "order_id":  "ord_ABC123XYZ"
  }
}

Event types

Signature scheme

Paperless verifies every webhook with HMAC-SHA256. Constant-time comparison; bad signature returns 401 Unauthorized with no body.

Canonical string

canonical_string = X-Paperless-Timestamp + "." + raw_request_body
signature        = HMAC-SHA256(WEBHOOK_SIGNING_SECRET, canonical_string)
header value     = hex(signature)         // lowercase, no prefix

Python reference

import hashlib
import hmac
import json
import time
import requests

def emit_webhook(event: dict) -> None:
    body = json.dumps(event, separators=(",", ":")).encode("utf-8")
    timestamp = str(int(time.time()))
    canonical = timestamp.encode("utf-8") + b"." + body
    signature = hmac.new(
        WEBHOOK_SIGNING_SECRET.encode("utf-8"),
        canonical,
        hashlib.sha256,
    ).hexdigest()

    requests.post(
        f"https://api.paperless.example/webhooks/{PROVIDER}",
        data=body,
        headers={
            "Content-Type":          "application/json",
            "X-Paperless-Signature": signature,
            "X-Paperless-Timestamp": timestamp,
        },
        timeout=5,
    )

Verifying on your side (test fixture)

Use this snippet to verify your own signatures locally before going live. Paperless will use the equivalent logic on its side.

import hashlib
import hmac

def verify(secret: str, body: bytes, timestamp: str, signature: str,
           max_skew_seconds: int = 300) -> bool:
    import time
    if abs(int(time.time()) - int(timestamp)) > max_skew_seconds:
        return False
    canonical = timestamp.encode("utf-8") + b"." + body
    expected = hmac.new(
        secret.encode("utf-8"), canonical, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

cURL

BODY='{"external_event_id":"evt_demo","event_type":"order.completed","created_at":"2026-05-15T17:21:19Z","merchant_id":"MERCHANT_12345","location_id":"LOC_001","data":{"order_id":"ord_demo"}}'
TS=$(date +%s)
SIG=$(printf '%s' "$TS.$BODY" | openssl dgst -sha256 -hmac "$WEBHOOK_SIGNING_SECRET" | awk '{print $2}')

curl -sS -X POST \
  -H "Content-Type: application/json" \
  -H "X-Paperless-Signature: $SIG" \
  -H "X-Paperless-Timestamp: $TS" \
  --data "$BODY" \
  "https://api.paperless.example/webhooks/acme"

Response codes

Timing

• Paperless will return 200 within ~500 ms — usually faster. The endpoint only verifies, persists the raw event, and enqueues for async processing.
• Your connect timeout should be 5 s; your read timeout 10 s. Anything longer indicates a Paperless infrastructure issue.
• The receipt becoming visible in the customer's app happens asynchronously after Paperless 200s your webhook. Typical end-to-end latency is 1–3 s.

Retry policy (yours)

You own webhook retries. The required schedule:

After 3 failed attempts, write the event to your local DLQ and alert your ops team. Same external_event_id on every retry; Paperless will dedupe.

Idempotency

• Paperless dedupes incoming webhooks by external_event_id. If you re-deliver the same event, you will receive a 200 with "duplicate": true and no side effect.
• Receipts are also deduped by external_id (the order ID inside the fetched order). Two distinct external_event_id values pointing at the same external_id still result in one receipt.
• Retries are safe by default. Always prefer a retry over a manual reconciliation.

Common signing mistakes

• Pretty-printed JSON. Sign the exact bytes you send. If you pretty-print after signing, the signature breaks.
• Mixed-case hex. Use lowercase hex.
• Skew. If your servers' clocks drift past 5 minutes, all signatures fail. Run NTP.
• Signing the URL. The canonical string is timestamp + "." + body — not the URL.
• Encoding the secret. The secret is bytes, taken as-is from what Paperless gives you. Do not base64-decode or hex-decode it.