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
| Event | When |
|---|---|
job.completed | Every 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.failed | Every document of the job failed. |
webhook.test | Sent 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.completedRedact-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
2xxquickly (a whole attempt is cut off after 20 seconds); read the body and do the work afterwards. Anything else (including3xx, 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 treatGET /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
redactedevent when you callPOST /v1/jobs/{job_id}/redact(which then just releases it). webhook.testis sent once, without retries, at most one every 10 seconds per account.- Delivery history is kept 30 days.