Webhook Task Retrieval

Instead of repeatedly polling the API for results, you can set up webhooks to automatically receive document data whenever processing is complete.

Overview

Webhooks allow Koncile to push extracted document data to your server as soon as processing finishes. This is more efficient than polling and enables real-time integrations.

Key features:

• Create multiple webhooks with different configurations

• Filter webhooks by folders and/or document templates

• Secure requests with signing secrets

• Choose between JSON and CSV output formats

• Test your endpoint before going live

Setting Up Webhooks

Accessing Webhook Configuration

1. Navigate to Settings > API in your Koncile dashboard

2. Only company administrators can create and manage webhooks

Creating a Webhook

Click the Add Webhook button to open the configuration dialog.

Configuration options:

Field	Description
Name	A descriptive name for your webhook (e.g., "staging", "production")
Select folders	Optional. Limit this webhook to documents from specific folders
Select document templates	Optional. Limit this webhook to documents matching specific templates
Your webhook URL	The endpoint URL where Koncile will send POST requests
Output format	Choose between JSON or CSV format
Signing secret	Optional. A secret key used to verify requests came from Koncile

Webhook Filtering

You can control which documents trigger a webhook by linking it to specific folders and/or document templates:

• No filters: Webhook receives all processed documents

• Folders only: Webhook receives documents from selected folders (regardless of template)

• Templates only: Webhook receives documents matching selected templates (regardless of folder)

• Both filters: Webhook receives documents that match either the selected folders OR the selected templates

Testing Your Webhook

Before saving, use the Test URL button to verify your endpoint is working correctly:

1. Enter your webhook URL

2. Click Test URL

3. Koncile will send a sample payload to your endpoint

4. The response will be displayed in the Response section

5. If successful, click Validate to save the webhook

Webhook Payload

JSON Format

When a document finishes processing, Koncile sends a POST request with the following JSON structure:

{
  "status": "DONE",
  "status_message": "Document processed successfully.",
  "task_id": "abc123-def456-ghi789",
  "document_id": "12345",
  "template_id": "67890",
  "document_name": "Invoice_2025_07_02.pdf",
  "General_fields": {
    "InvoiceNumber": {
      "value": "INV-2025-001",
      "confidence_score": 0.98
    },
    "InvoiceDate": {
      "value": "2025-07-02",
      "confidence_score": 0.95
    }
  },
  "Line_fields": {
    "Product": [
      { "value": "Widget A", "confidence_score": 0.92 },
      { "value": "Widget B", "confidence_score": 0.89 }
    ],
    "Quantity": [
      { "value": "10", "confidence_score": 0.95 },
      { "value": "5", "confidence_score": 0.93 }
    ]
  }
}

Payload fields:

Field	Description
status	Processing status: DONE, DUPLICATE, IN_PROGRESS, or FAILED
status_message	Human-readable status description
task_id	Unique identifier for the processing task
document_id	Unique identifier for the processed document
template_id	ID of the document template used for extraction
document_name	Original filename of the uploaded document
General_fields	Object containing extracted single-value fields with confidence scores
Line_fields	Object containing extracted multi-value/line item fields

CSV Format

When CSV format is selected, Koncile sends a multipart/form-data POST request with a CSV file attachment containing the extracted data.

Securing Webhooks with Signing Secrets

Signing secrets allow you to verify that webhook requests genuinely come from Koncile.

Generating a Signing Secret

1. In the webhook configuration dialog, the signing secret section shows your current secret (if any)

2. Click the create button to generate a new secret

3. The secret follows the format: whsec_xxxxxxxxxxxxxxxx

4. Important: Copy and store your secret securely - you'll need it to verify requests

How Signature Verification Works

When a signing secret is configured, Koncile includes two additional headers with each request:

Header	Description
X-Koncile-Signature	HMAC-SHA256 signature of the payload
X-Koncile-Timestamp	Unix timestamp when the request was signed

The signature is computed as:

HMAC-SHA256(secret, "{timestamp}.{payload}")

Where {payload} is the raw JSON body (with minimal whitespace).

Verifying Signatures

To verify a webhook request:

1. Extract the X-Koncile-Signature and X-Koncile-Timestamp headers

2. Check that the timestamp is recent (within 5 minutes) to prevent replay attacks

3. Compute the expected signature using your secret

4. Compare the computed signature with the received signature

Implementation Examples

Python

import hashlib
import hmac
import time
from fastapi import FastAPI, Request, HTTPException

app = FastAPI()

WEBHOOK_SECRET = "whsec_your_secret_here"

def verify_signature(payload: bytes, signature: str, timestamp: str) -> bool:
    try:
        ts = int(timestamp)
    except (ValueError, TypeError):
        return False

    if abs(time.time() - ts) > 300:
        return False

    message = f"{ts}.{payload.decode('utf-8')}"
    expected = hmac.new(
        WEBHOOK_SECRET.encode("utf-8"),
        message.encode("utf-8"),
        hashlib.sha256,
    ).hexdigest()

    return hmac.compare_digest(signature, expected)

@app.post("/webhook")
async def receive_webhook(request: Request):
    body = await request.body()

    signature = request.headers.get("X-Koncile-Signature")
    timestamp = request.headers.get("X-Koncile-Timestamp")

    if signature and timestamp:
        if not verify_signature(body, signature, timestamp):
            raise HTTPException(status_code=401, detail="Invalid signature")

    payload = await request.json()

    task_id = payload.get("task_id")
    status = payload.get("status")
    document_name = payload.get("document_name")

    print(f"Received webhook for task {task_id}: {status} - {document_name}")

    if status == "DONE":
        general_fields = payload.get("General_fields", {})
        line_fields = payload.get("Line_fields", {})

    return {"status": "received"}

Run with:

pip install fastapi uvicorn
uvicorn main:app --host 0.0.0.0 --port 8000

JavaScript

Managing Multiple Webhooks

You can create multiple webhooks to handle different scenarios:

• Development vs Production: Create separate webhooks for staging and production environments

• Department-specific: Route invoices to your accounting system and contracts to your legal system

• Backup endpoints: Configure multiple webhooks as redundancy

Each webhook operates independently - a document can trigger multiple webhooks if it matches their filter criteria.

Troubleshooting

Webhook not triggering

• Verify the webhook is activated (toggle should be enabled)

• Check that your filters match the documents you're processing

• Ensure your endpoint returns a 2xx status code

Invalid signature errors

• Confirm you're using the correct signing secret

• Check that the timestamp hasn't expired (requests older than 5 minutes are rejected)

• Ensure you're computing the signature with the raw JSON body (minimal whitespace)

Missing data in payload

• Verify the document finished processing successfully (status should be DONE)

• Check that your document template has the expected fields configured