Webhook

A webhook is an HTTP callback sent to your endpoint when an event occurs. DocLD uses webhooks to notify your system about document processing, extraction completion, and workflow events. Instead of polling for status, your server receives a POST request when an event fires.

Webhook Events

Register a webhook URL and select which events to receive. DocLD sends a POST request with a JSON payload describing the event, including document ID, job ID, status, and relevant metadata.

Payload Structure

Webhook payloads follow a consistent structure:

{
  "event": "document.processed",
  "timestamp": "2024-01-15T12:00:00Z",
  "data": {
    "document_id": "...",
    "status": "completed",
    "page_count": 10
  }
}

The event field identifies the type; data contains event-specific details. For extraction completion, data includes job ID and schema ID.

Configuration

Register webhooks via the dashboard or API:

• URL — Your endpoint URL (must be HTTPS)
• Events — Select which events to receive
• Secret — Signing secret for request verification

DocLD signs webhook requests with the secret. Verify the signature to ensure requests are from DocLD and have not been tampered with.

Retries and Reliability

Webhooks are retried on failure:

• Retry policy — Exponential backoff over a configured period
• Status codes — 2xx accepts the webhook; 4xx/5xx triggers retries
• Delivery status — Monitor delivery status in the dashboard; failed deliveries are logged

Ensure your endpoint responds with 2xx quickly (e.g., within 30 seconds). Process the payload asynchronously if needed.

Security and Verification

Verify webhook requests using the signing secret:

1. Extract the signature from the request header
2. Compute HMAC of the raw body using your secret
3. Compare with the provided signature

Reject requests with invalid signatures. Never expose the signing secret in client-side code.

Use Cases

• Trigger downstream systems — When a document is ready, sync to your database or start another workflow
• Sync extraction results — Push extraction results to your CRM, ERP, or internal systems
• Notify users — Send email or in-app notifications when processing completes
• Integrate with workflows — Use webhooks as workflow triggers for automation

Related Concepts

Webhooks notify you when jobs complete. Workflows can be triggered by webhooks or send webhook events. The API provides programmatic access; webhooks provide event-driven integration.