Webhooks

Receive HTTP POSTs when extraction completes (or fails). Prefer webhooks over polling for production.

Event types

Subscribe when creating a webhook (POST /api/v1/protected/webhooks with url and events array).

Event	When
document.uploaded	Document finished uploading
document.extraction.completed	Extraction finished
bank_statement.extraction.completed	Bank statement job succeeded
invoice.extraction.completed	Invoice job succeeded
form.extraction.completed	Form (tax) job succeeded
document.extraction.failed	Extraction failed

GET /api/v1/protected/webhooks/events returns the full list.

Payload and headers

We POST JSON to your URL. Headers include:

Content-Type: application/json
X-DocuClipper-Signature – HMAC-SHA256 of raw body (hex)
X-DocuClipper-Event – event type
X-DocuClipper-Event-Id – delivery id

json

{
  "job_id": "12345",
  "status": "Succeeded",
  "event": "bank_statement.extraction.completed"
}

Use job_id to call POST /api/v1/protected/job/:id/export.

Verifying signatures

Compute HMAC-SHA256 of the raw request body with your webhook secret; compare hex digest to X-DocuClipper-Signature.

javascript

const crypto = require('crypto');
function verifySignature(rawBody, signature, secret) {
  const expected = crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(signature, 'hex'), Buffer.from(expected, 'hex'));
}
const isValid = verifySignature(req.rawBody, req.headers['x-docuclipper-signature'], process.env.WEBHOOK_SECRET);

Retries

Failed deliveries are retried with exponential backoff. Return 2xx quickly to acknowledge receipt. Process asynchronously if needed.