Webhook Callbacks (Outbound)

Overview

1Flow 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: 1Flow-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 });
});

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

Next Steps

• Learn about webhook uploads for sending documents to 1Flow
• Explore webhook get for retrieving document data
• Explore the Browse App to view your processed documents