Webhooks API

Configure webhooks to receive real-time notifications for platform events.

Overview

Webhooks allow your application to receive HTTP callbacks when events occur in DocLD. Configure webhook URLs to be notified when:

Documents finish processing
Extractions complete
Workflows execute
Chat messages are received

Webhook Events

Document Events

Event	Description
`document.uploaded`	New document uploaded
`document.processing`	Document processing started
`document.completed`	Document finished processing
`document.failed`	Document processing failed
`document.deleted`	Document deleted

Extraction Events

Event	Description
`extraction.started`	Extraction started
`extraction.completed`	Extraction finished successfully
`extraction.failed`	Extraction failed

Chat Events

Event	Description
`chat.message`	New chat message
`chat.session.created`	New chat session created

Workflow Events

Event	Description
`workflow.started`	Workflow execution started
`workflow.completed`	Workflow finished
`workflow.failed`	Workflow failed
`workflow.step.completed`	Individual step completed

Split Events

Event	Description
`split.completed`	Split job finished successfully
`split.failed`	Split job failed

Split webhooks are sent when you provide webhook_url on POST /api/split/run (async) or POST /api/split/batch. Payload includes job_id, document_id, status, sections_summary, results_url, and optionally error. See Split API for the full payload.

Webhook Payload

All webhook payloads follow this structure:


{
  "event": "document.completed",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "id": "doc-uuid",
    "name": "invoice.pdf",
    "status": "completed",
    "metadata": {...}
  },
  "webhook_id": "webhook-uuid"
}

Document Completed Payload


{
  "event": "document.completed",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "id": "doc-uuid",
    "name": "invoice.pdf",
    "status": "completed",
    "file_type": "pdf",
    "file_size": 125000,
    "pages": 5,
    "processing_time_ms": 3500
  }
}

Extraction Completed Payload


{
  "event": "extraction.completed",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "extraction_id": "extraction-uuid",
    "document_id": "doc-uuid",
    "schema_id": "schema-uuid",
    "overall_confidence": 0.95,
    "fields_extracted": 8,
    "data": {
      "invoice_number": "INV-001",
      "total_amount": 1250.00
    }
  }
}

Webhook Security

Signature Verification

Webhooks include a signature header for verification:


X-DocLD-Signature: sha256=abc123...

Verify the signature using your webhook secret:


const crypto = require('crypto');
 
function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  
  return `sha256=${expected}` === signature;
}

Webhook Secret

Your webhook secret is generated when you create a webhook configuration. Store it securely and use it to verify incoming webhooks.

Retry Policy

Failed webhook deliveries are retried with exponential backoff:

Attempt	Delay
1	Immediate
2	1 minute
3	5 minutes
4	30 minutes
5	2 hours

After 5 failed attempts, the webhook is marked as failed.

Webhook Configuration

Configure webhooks in the dashboard under Settings → Webhooks or via API:

Create Webhook


curl -X POST "https://your-domain.com/api/webhooks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhook",
    "events": ["document.completed", "extraction.completed"],
    "organization_id": "org-uuid"
  }'

Async Parsing Webhooks

When using /api/parse/async, specify a webhook URL to receive results:


{
  "input": "https://example.com/document.pdf",
  "webhook_url": "https://your-server.com/parse-complete"
}

The webhook receives:


{
  "job_id": "job-uuid",
  "status": "completed",
  "result": {
    "chunks": [...],
    "usage": {
      "num_pages": 5,
      "credits": 7.5
    }
  }
}

Split Webhooks

When using POST /api/split/run (async) or POST /api/split/batch, pass webhook_url to receive a POST when each split job completes or fails.

Example payload:


{
  "event": "split.completed",
  "job_id": "split-job-uuid",
  "document_id": "doc-uuid",
  "status": "completed",
  "sections_summary": [
    { "section_id": "sec-1", "name": "Introduction", "page_start": 1, "page_end": 5, "type": "section" }
  ],
  "results_url": "https://app.docld.com/split?job=split-job-uuid",
  "timestamp": "2024-01-15T10:30:00Z"
}

For split.failed, the payload includes an error field. See Split API for full details.

Best Practices

Respond quickly - Return 200 within 30 seconds
Process async - Queue webhook handling, don’t block
Verify signatures - Always verify webhook authenticity
Handle duplicates - Webhooks may be sent multiple times
Log payloads - Keep logs for debugging
Use HTTPS - Only configure HTTPS webhook URLs