Developer docs

Webhooks

Signed job.completed and job.failed webhooks for API jobs: set up an endpoint, verify the HMAC-SHA256 signature in Python or Node, retries and the replay window.

Webhooks

Get a signed HTTPS request when an API job finishes, instead of polling GET /v1/jobs/{job_id}.

Set up an endpoint

In the dashboard, open Settings → Webhooks, enter your receiver URL and copy the signing secret (whsec_…). It is shown once; Rotate secret replaces it at once. Up to 5 endpoints per account. Send test queues a webhook.test event.

The URL must use https on port 443 or 8443 and resolve to a public address: private, loopback, link-local and reserved addresses (and names such as localhost or *.internal) are refused, when you add the endpoint and again at every delivery. Redirects are not followed: point the endpoint at its final URL.

Events

EventWhen
job.completedEvery document of an API job is finished and at least one succeeded. data.status is redacted, or detected for a detect-only job. A detect-only job that you redact later sends a second job.completed with status: "redacted".
job.failedEvery document of the job failed.
webhook.testSent from the dashboard. data is empty.

Webhooks are sent for jobs created through the API (and the AI connectors), not for dashboard uploads. A direct upload (POST /v1/jobs/init) that is never committed is removed after an hour and sends no event.

Payload

{
  "id": "evt_6f1c0e8a2b9d4c3e8f7a6b5c4d3e2f10",
  "type": "job.completed",
  "created_at": "2026-11-21T10:15:03Z",
  "data": {
    "job_id": "b3f2b2e0-6f30-4f3e-8a7b-2f2a20a7d91c",
    "status": "redacted",
    "mode": "redact",
    "detect_only": false,
    "sandbox": false,
    "retention": "ephemeral",
    "page_count": 3,
    "documents": [
      { "id": "7f4f4f85-6b7a-4f88-9a8a-7b9a6a2d2fd0", "status": "redacted", "page_count": 3 }
    ],
    "created_at": "2026-11-21T10:14:41Z"
  }
}

Ids, statuses, modes, page counts and times only: never file names, document text or error messages. Fetch details with your API key (GET /v1/jobs/{job_id}, GET /v1/documents/{doc_id}/entities, downloads).

Headers:

  • Redact-PDF-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256>
  • Redact-PDF-Event: job.completed
  • Redact-PDF-Event-Id: evt_… — the same for every retry of one event: use it to drop duplicates.

Verify the signature

The signature is HMAC-SHA256 of "{t}.{raw request body}" with your secret. Verify it on the raw bytes you received (before any JSON parsing), compare in constant time, and refuse a t more than 5 minutes from your clock (replay window).

Python

import hashlib, hmac, time

def verify(secret: str, header: str, body: bytes, tolerance: int = 300) -> bool:
    try:
        parts = dict(item.split("=", 1) for item in header.split(","))
        timestamp = int(parts["t"])
    except (ValueError, KeyError):
        return False
    if abs(time.time() - timestamp) > tolerance:
        return False
    expected = hmac.new(secret.encode(), f"{timestamp}.".encode() + body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected.encode(), parts.get("v1", "").encode())

# Flask: verify(SECRET, request.headers["Redact-PDF-Signature"], request.get_data())

Node.js

import crypto from 'node:crypto';

export function verify(secret, header, rawBody, toleranceSeconds = 300) {
  const parts = Object.fromEntries((header ?? '').split(',').map((p) => p.split('=', 2)));
  const timestamp = Number.parseInt(parts.t, 10);
  if (!Number.isFinite(timestamp) || Math.abs(Date.now() / 1000 - timestamp) > toleranceSeconds) return false;
  const expected = crypto.createHmac('sha256', secret).update(`${timestamp}.`).update(rawBody).digest('hex');
  const given = Buffer.from(parts.v1 ?? '', 'utf8');
  return given.length === expected.length && crypto.timingSafeEqual(given, Buffer.from(expected, 'utf8'));
}

// Express: app.post('/webhooks/redact-pdf', express.raw({ type: 'application/json' }),
//   (req, res) => verify(SECRET, req.get('Redact-PDF-Signature'), req.body) ? res.sendStatus(204) : res.sendStatus(400));

Delivery and retries

  • Answer with any 2xx quickly (a whole attempt is cut off after 20 seconds); read the body and do the work afterwards. Anything else (including 3xx, timeouts and TLS errors) is a failed attempt.
  • Failed attempts are retried after 30 s, 2 min, 10 min, 30 min, 1 h, 3 h, 6 h and 12 h (9 attempts, about a day), then the delivery is given up. The dashboard shows the latest delivery of each endpoint.
  • Deliveries can arrive more than once and out of order: deduplicate on Redact-PDF-Event-Id, and treat GET /v1/jobs/{job_id} as the source of truth.
  • One event per finish: a job that finishes again (redacted after a detection, or reprocessed from the dashboard) sends a new event with a new id. A detect-only job whose documents are saved from the Studio instead sends its redacted event when you call POST /v1/jobs/{job_id}/redact (which then just releases it).
  • webhook.test is sent once, without retries, at most one every 10 seconds per account.
  • Delivery history is kept 30 days.

Related pages