🔗 Webhooks

Webhooks allow you to receive real-time notifications when specific events occur in the Docflo platform. By configuring a webhook, you can automatically trigger actions in your external systems whenever documents are processed, approved, or undergo other status changes.

✨ Key Benefits:

Receive instant notifications when platform events occur
Automate workflows by connecting Docflo to your business systems
Secure communication with multiple authentication options
Full document data included in webhook payloads

🚀 How Webhooks Work

Create a webhook in the Docflo platform with your HTTPS endpoint
Select the event that should trigger the webhook
Configure authentication to secure the communication
Activate the webhook to start receiving notifications

When the configured event occurs, Docflo sends an HTTP POST request to your endpoint with the event details and full document data.

Webhook Requirements

To create a webhook, you need to provide the following:

Requirement	Description
HTTPS Endpoint	A secure HTTPS URL that will receive the webhook payload. HTTP endpoints are not supported for security reasons.
Platform Event	The specific event that will trigger the webhook call (e.g., document processed, document approved).
Authorization	Authentication method for securing the webhook (see Authentication Options below).
Signing Secret	(Optional) A secret key used to sign webhook payloads for additional verification.

Authentication Options

Webhooks support multiple authentication methods to secure communication between Docflo and your endpoint:

None

No authentication is applied. The webhook will be sent without any authorization headers. Use this only for testing or internal endpoints with other security measures in place.

Basic Authentication

Uses HTTP Basic Authentication with a username and password.

Authorization: Basic base64(username:password)

Bearer Token

Uses a bearer token for authentication.

Authorization: Bearer <your-token>

API Key

Sends an API key in a custom header.

x-api-key: <your-api-key>

Webhook Status

Webhooks can be set to one of two states:

Status	Description
Active	The webhook is enabled and will send notifications when the configured event occurs.
Inactive	The webhook is disabled and will not send any notifications. Use this to temporarily pause a webhook without deleting it.

Webhook Payload

When a webhook is triggered, Docflo sends an HTTP POST request to your configured endpoint with the following JSON payload:

{
  "event": "document.processed",
  "tenantId": "your-tenant-id",
  "timestamp": "2025-03-10T17:53:46.000Z",
  "doc": {
    "_id": "document-id",
    "type": "invoice",
    "status": "ANALYZED",
    "createdAt": "2025-03-10T17:50:00.000Z",
    "updatedAt": "2025-03-10T17:53:46.000Z",
    "fields": {
      "InvoiceId": "INV-2025-001",
      "VendorName": "Acme Corporation",
      "InvoiceDate": "2025-03-01",
      "InvoiceTotal": {
        "Amount": 1500.00,
        "CurrencyCode": "USD"
      },
      "Items": [
        {
          "Description": "Professional Services",
          "Quantity": 10,
          "UnitPrice": 150.00,
          "Amount": 1500.00
        }
      ]
    }
  }
}

Payload Fields

Field	Type	Description
`event`	string	The event type that triggered the webhook (e.g., `document.processed`, `document.approved`).
`tenantId`	string	Your unique tenant identifier in the Docflo platform.
`timestamp`	date	ISO 8601 formatted timestamp of when the event occurred.
`doc`	object	The complete document data including all extracted fields and metadata.

Signing Secret (Optional)

For additional security, you can configure a signing secret for your webhook. When a signing secret is set, Docflo includes a signature header with each request that you can use to verify the payload authenticity.

Verifying the Signature

The signature is computed using HMAC-SHA256 and included in the X-Docflo-Signature header:

X-Docflo-Signature: sha256=<computed-signature>

Example verification (Node.js):

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

// In your webhook handler
app.post('/webhook', (req, res) => {
  const signature = req.headers['x-docflo-signature'];
  const isValid = verifyWebhookSignature(req.body, signature, 'your-signing-secret');
  
  if (!isValid) {
    return res.status(401).send('Invalid signature');
  }
  
  // Process the webhook
  console.log('Received event:', req.body.event);
  res.status(200).send('OK');
});

Platform Events

The following events can trigger webhooks:

Event	Description
`document.created`	A new document has been uploaded to the platform.
`document.processed`	Document processing and extraction has been completed.
`document.approved`	A document has been approved in the approval workflow.
`document.rejected`	A document has been rejected in the approval workflow.
`document.status_changed`	The document status has changed.

Best Practices

Use HTTPS: Always use secure HTTPS endpoints to protect sensitive document data in transit.
Implement Signature Verification: Use the signing secret feature to verify that webhook requests originate from Docflo.
Respond Quickly: Return a 2xx response within 30 seconds. Process webhook data asynchronously if needed.
Handle Retries: Docflo may retry failed webhook deliveries. Implement idempotency to handle duplicate events gracefully.
Secure Your Endpoint: Use authentication and restrict access to your webhook endpoint to prevent unauthorized access.
Log Webhook Events: Keep logs of received webhooks for debugging and audit purposes.

Troubleshooting

Webhook Not Receiving Events

Verify the webhook is set to Active status
Ensure your endpoint is accessible from the internet
Check that your endpoint returns a 2xx status code
Verify the correct event type is selected

Authentication Failures

Double-check your authentication credentials
Ensure the authorization header format matches your endpoint's expectations
For API Key authentication, verify the header name matches what your server expects

Invalid Signature

Ensure you're using the correct signing secret
Verify you're computing the signature on the raw request body
Check that the payload hasn't been modified before verification

Example: Setting Up a Webhook Endpoint

Here's a complete example of a webhook endpoint using Express.js:

import express from 'express';
import crypto from 'crypto';

const app = express();
app.use(express.json());

const SIGNING_SECRET = process.env.WEBHOOK_SIGNING_SECRET;

// Middleware to verify webhook signature
function verifySignature(req, res, next) {
  const signature = req.headers['x-docflo-signature'];
  
  if (SIGNING_SECRET && signature) {
    const expectedSignature = 'sha256=' + crypto
      .createHmac('sha256', SIGNING_SECRET)
      .update(JSON.stringify(req.body))
      .digest('hex');
    
    if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expectedSignature))) {
      return res.status(401).json({ error: 'Invalid signature' });
    }
  }
  
  next();
}

app.post('/webhooks/docflo', verifySignature, async (req, res) => {
  const { event, tenantId, timestamp, doc } = req.body;
  
  console.log(`Received ${event} event for tenant ${tenantId}`);
  console.log(`Document ID: ${doc._id}, Type: ${doc.type}`);
  
  // Process the webhook asynchronously
  switch (event) {
    case 'document.processed':
      // Handle processed document
      await processDocument(doc);
      break;
    case 'document.approved':
      // Handle approved document
      await syncToERP(doc);
      break;
    case 'document.rejected':
      // Handle rejected document
      await notifyTeam(doc);
      break;
  }
  
  // Respond quickly to acknowledge receipt
  res.status(200).json({ received: true });
});

app.listen(3000, () => {
  console.log('Webhook server listening on port 3000');
});

API Integration - Learn about the Docflo REST API
Data Types - Understand the data structures used in document fields
Automations - Set up automated workflows triggered by document events

🚀 How Webhooks Work​

Webhook Requirements​

Authentication Options​

None​

Basic Authentication​

Bearer Token​

API Key​

Webhook Status​

Webhook Payload​

Payload Fields​

Signing Secret (Optional)​

Verifying the Signature​

Platform Events​

Best Practices​

Troubleshooting​

Webhook Not Receiving Events​

Authentication Failures​

Invalid Signature​

Example: Setting Up a Webhook Endpoint​

Related Documentation​