Polling vs Webhook

Two ways to learn that an extraction batch has finished. Both are fully supported — pick based on your deployment model.

At a glance

	Polling	Webhook
Setup	None — just call `GET`	Register one URL in the dashboard
Server-side infra	None	An HTTP endpoint you can reach
Latency	Bounded by your poll interval	Push as soon as we finish (typically < 1s)
Cost	Higher HTTP traffic	Lower
Retry on failure	You handle it	We retry up to 3 days with backoff
Best for	CLI tools, scripts, prototypes	Production integrations, async pipelines

Polling

Call GET /extractions/{extraction_id}/batches/{batch_id} on a schedule until status is processed (or partial / failed).

javascript

async function waitForBatch(extractionId, batchId, apiKey) {
  while (true) {
    const res = await fetch(
      `https://api.docparse-labs.vercel.app/v1/extractions/${extractionId}/batches/${batchId}`,
      { headers: { Authorization: `Bearer ${apiKey}` } },
    );
    const { batch } = await res.json();
    if (["processed", "partial", "failed"].includes(batch.status)) return batch;
    await new Promise(r => setTimeout(r, 2000));   // wait 2s
  }
}

Be respectful with poll frequency. Once every 2-5 seconds is plenty. Sub-second polling will eat your rate limit.

Webhook

Configure one webhook URL on the dashboard's API → Webhook Settings card. When any batch finishes, we POST to that URL.

http

POST /your-endpoint
Content-Type: application/json
webhook-id: evt_01HQX...
webhook-timestamp: 1716543600
webhook-signature: v1,3xnGUiH8sX3lFvHl1...
 
{
  "type": "extraction.completed",
  "data": {
    "extraction_id": "ext_01HQX...",
    "batch_id":      "btc_01HQX...",
    "status": "processed",
    "files": [
      { "id": "file_01HQX...", "status": "processed" }
    ]
  }
}

Always verify the signature before trusting the payload — see Webhook for the verification code.

When does each fire?

Polling returns the latest snapshot whenever you ask.
Webhooks fire on these events: extraction.completed, extraction.failed, file.processed, file.failed, plus classification equivalents. Full list in Webhook Event Types.

Use both

There's no rule against doing both. Production systems often:

Rely on webhooks for primary delivery.
Run a nightly polling job as a safety net for any deliveries lost to a customer outage longer than our retry window.