Webhooks

Webhooks allow your application to receive real-time notifications when events occur in your DocuRift account. Instead of continuously polling our API to check if a document has finished processing, webhooks push updates to your application the moment something happens. This event-driven approach is more efficient, more reliable, and enables you to build responsive document processing workflows.

Overview

Webhooks work by sending HTTP POST requests to an endpoint you specify whenever certain events occur. When you configure a webhook, you choose which events you want to receive and provide a URL where DocuRift should send the notifications.

Instead of polling our API for updates, configure a webhook endpoint to receive HTTP POST requests whenever:

• A document finishes processing successfully
• Document processing fails with an error
• Your credit balance falls below a specified threshold
• API keys are created or revoked
• Batch processing jobs complete

Webhooks are essential for building production-ready document processing pipelines. They enable you to trigger downstream workflows immediately when documents are processed, send notifications to users, update databases, or integrate with other services in your stack.

Getting Started

Why Use Webhooks?

Webhooks provide several advantages over polling-based approaches. Here's how they compare:

| Polling | Webhooks | |---------|----------| | Frequent API calls consume rate limits | Only sends requests when events occur | | Delayed notifications (depends on poll interval) | Real-time updates within seconds | | Wastes compute resources and bandwidth | Efficient use of resources | | Simple to implement initially | Requires endpoint setup but scales better | | Higher latency for user experience | Immediate response enables better UX |

For high-volume document processing, webhooks are strongly recommended. They reduce load on both your servers and our API, while providing faster notifications than any reasonable polling interval could achieve.

Common Use Cases

Webhooks enable a wide variety of automation scenarios:

• Accounts Payable Automation: When an invoice finishes processing, automatically create a record in your accounting system
• Shipping Integration: When a bill of lading is extracted, update your TMS or WMS system with the shipment details
• Notification Systems: Alert users via email or Slack when their documents are ready
• Data Pipelines: Push extracted data to data warehouses, ETL tools, or business intelligence platforms
• Error Handling: Get immediate alerts when document processing fails so you can investigate and retry

Quick Example

When a document is processed, you'll receive a POST request with a JSON payload like this:

{
  "event": "document.completed",
  "timestamp": "2026-02-02T10:30:00Z",
  "data": {
    "documentId": "doc_abc123",
    "jobId": "job_xyz789",
    "status": "completed",
    "confidence": 0.95
  }
}

Your endpoint should respond with a 2xx status code to acknowledge receipt. If we don't receive a successful response, we'll retry the webhook with exponential backoff for up to 24 hours.

Security

Security is critical when implementing webhooks. All webhook requests include:

• Timestamp: When the event occurred (use this to prevent replay attacks)
• Signature: HMAC-SHA256 signature for verification
• Event ID: Unique identifier for deduplication

Always verify webhook signatures to ensure requests are from DocuRift and haven't been tampered with. Never process webhook payloads without verifying the signature first. This protects your application from malicious actors who might try to send fake webhook events to your endpoint.