Callbacks (Outbound)

Overview

DocVision sends HTTP webhooks to your server when documents are fully processed and indexed. This allows you to integrate document processing events into your own systems, workflows, or applications.

How It Works

When a document completes processing:

1. Document Processing - Document goes through classification, extraction, and indexing
2. Webhook Dispatch - If webhook callback URL is configured, a POST request is sent to your endpoint
3. Payload Delivery - Your server receives the document data including extracted fields and line items

Setup

Configure your webhook callback URL in Organization Settings > Webhooks section. Optionally configure a Webhook Signing Secret for enhanced security.

API Reference

Request Method

POST {your-endpoint-url}

Headers

When a webhook signing secret is configured:

• Content-Type: application/json
• X-Webhook-Signature - HMAC-SHA256 signature of the payload
• X-Webhook-Timestamp - Unix timestamp (milliseconds) when the webhook was sent
• User-Agent: DocVision-Webhook/1.0

Payload Format

{
  "event": "document.ready",
  "success": true,
  "documentId": "doc_abc123xyz",
  "status": {
    "extractionStatus": "INDEXED",
    "docType": "INVOICE",
    ...
  },
  "document": {
    ...
  },
  "extraction": {
    "fields": {
      ...
    },
    "tables": {
      "items": [
        {
          ...
      ]
    }
  }
}

Payload Fields

Top-Level Fields

Status Object

Document Object

Extraction Object

Expected Response

Your endpoint should return a 2xx status code (200, 201, 202, etc.) to indicate successful receipt.

Recommended Response:

{
  "received": true,
  "message": "Webhook processed successfully"
}

Code Examples

app.post('/webhook', express.json(), (req, res) => {
  const { event, documentId, status, document, extraction } = req.body;
  
  // Handle different event types
  if (event === 'document.ready') {
    console.log('Document ready:', documentId);
    console.log('Status:', status.extractionStatus);
    
    if (document) {
      console.log('Document summary:', document.description);
      console.log('Total amount:', document.totalAmount);
    }
    
    if (extraction) {
      console.log('Extracted fields:', extraction.fields);
      console.log('Extracted tables:', extraction.tables);
    }
  }
  
  res.status(200).json({ received: true });
});

Signature Verification

When a webhook signing secret is configured, you should verify the signature to ensure the webhook is authentic and hasn't been tampered with.

import crypto from 'crypto';

function verifyWebhookSignature(
  payload: string,
  signature: string,
  timestamp: string,
  secret: string
): boolean {
  const signaturePayload = `${timestamp}.${payload}`;
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(signaturePayload)
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-webhook-signature'] as string;
  const timestamp = req.headers['x-webhook-timestamp'] as string;
  
  if (!verifyWebhookSignature(req.body.toString(), signature, timestamp, WEBHOOK_SECRET)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }
  
  const data = JSON.parse(req.body.toString());
  // Process verified webhook...
  res.status(200).json({ received: true });
});

Testing

Use the Test Webhook button in Organization Settings > Webhooks section to send a test webhook to your configured endpoint URL.

Troubleshooting

Webhooks Not Received

• Verify your endpoint URL is correct and accessible from the internet
• Check that your server is running and can receive POST requests
• Ensure your firewall/security groups allow incoming connections
• Check server logs for incoming requests

Invalid Signature Errors

• Verify your webhook signing secret matches the one in Organization Settings
• Ensure you're computing the signature correctly (timestamp + payload, HMAC-SHA256)
• Check that you're using the raw JSON payload string, not a parsed object

Timeout Errors

• Ensure your endpoint responds within 10 seconds
• Process webhook data asynchronously if processing takes longer
• Return a success response immediately, then process the data in the background

Missing Extracted Data

• extraction may be null if extraction failed, document type doesn't have extractable fields, or document is still processing
• document may be null if extraction is not yet complete - check status.extractionStatus to see the current state

Frequently Asked Questions

Does DocVision retry failed webhook deliveries?

Currently, webhooks are sent once. If your endpoint is unavailable, the webhook will not be retried. You can always use the Get API to retrieve document data that may have been missed.

Can I receive webhooks for specific document types only?

Webhooks are sent for all documents that reach INDEXED status. Filter by status.docType in your webhook handler to process only specific document types.

What is the webhook timeout?

Your endpoint must respond within 10 seconds. If processing takes longer, return a 200 response immediately and process the data asynchronously in the background.

When should I use webhooks vs polling?

Use webhooks for production integrations with high document volumes - they're more efficient and real-time. Use polling (see Upload + Polling Example) for simpler integrations, testing, or when you can't expose a public endpoint.

Next Steps

• Learn about the Upload API for sending documents to DocVision
• Explore the Get API for retrieving document data
• See the Upload + Polling Example for a complete integration workflow
• Read the API Overview for all integration methods