Récupération des tâches par Webhook

As an option, you can chose instead of polling, to set up an endpoint that will automatically receive the document's extracted data whenever it is done parsing.

Présentation

Koncile fournit une fonctionnalité webhook pour livrer automatiquement les données extraites des documents à votre serveur une fois le traitement terminé, plutôt que de nécessiter des interrogations API répétées. Cela permet des capacités d'intégration en temps réel.

Capacités clés :

• Configurations webhook multiples avec fonctionnement indépendant

• Filtrage par Folders et/ou Templates de documents

• Vérification des requêtes via des secrets de signature

• Options de format de sortie JSON et CSV

• Test des endpoints avant déploiement

Configuration des Webhooks

Accéder à la configuration Webhook

1. Naviguez vers Paramètres > API dans votre tableau de bord Koncile

2. Seuls les administrateurs de l'entreprise ont les permissions de création et gestion des webhooks

Créer un Webhook

Accédez à l'interface de configuration via le bouton Ajouter un Webhook.

Champs de configuration :

Champ	Détails
Name	Identifiant descriptif pour le webhook (ex : "staging", "production")
Select folders	Optionnel. Restreindre le webhook aux documents de Folders spécifiques
Select document templates	Optionnel. Restreindre le webhook aux documents correspondant à des Templates spécifiques
Your webhook URL	URL de l'endpoint pour les requêtes POST
Output format	Sélection JSON ou CSV
Signing secret	Optionnel. Clé secrète pour la vérification des requêtes

Filtrage Webhook

Contrôlez le déclenchement des documents via le lien Folder et Template :

• Pas de filtres : Traite tous les documents terminés

• Folders uniquement : Traite les documents des Folders sélectionnés quel que soit le Template

• Templates uniquement : Traite les documents correspondant aux Templates sélectionnés quel que soit le Folder

• Les deux filtres : Traite les documents correspondant soit aux Folders sélectionnés OU aux Templates sélectionnés

Tester votre Webhook

Avant le déploiement, utilisez le bouton Test URL pour valider le fonctionnement de l'endpoint :

1. Entrez l'URL de votre webhook

2. Cliquez sur Test URL

3. Koncile envoie un payload d'exemple à votre endpoint

4. La réponse s'affiche dans la section Response

5. Cliquez sur Validate pour sauvegarder en cas de succès

Payload Webhook

Format JSON

Koncile transmet une requête POST avec cette structure JSON à la fin du traitement du document :

{
  "status": "DONE",
  "status_message": "Document processed successfully.",
  "task_id": "abc123-def456-ghi789",
  "document_id": "12345",
  "template_id": "67890",
  "document_name": "Facture_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 }
    ]
  }
}

Champs du payload :

Champ	Description
status	Résultat du traitement : DONE, DUPLICATE, IN_PROGRESS ou FAILED
status_message	Explication du statut lisible par un humain
task_id	Identifiant unique de la tâche de traitement
document_id	Identifiant unique du document traité
template_id	ID du Template utilisé pour l'extraction
document_name	Nom du fichier original téléchargé
General_fields	Fields extraits à valeur unique avec métriques de confiance
Line_fields	Fields extraits multi-valeurs/lignes

Format CSV

Les requêtes au format CSV arrivent comme requêtes POST multipart/form-data avec les données extraites contenues dans un fichier CSV joint.

Sécuriser les Webhooks avec des Signing Secrets

Les signing secrets permettent de vérifier que les requêtes webhook proviennent de Koncile.

Générer un Signing Secret

1. Dans la boîte de dialogue de configuration du webhook, localisez la section signing secret

2. Cliquez sur créer pour générer un nouveau secret

3. Les secrets suivent le format : whsec_xxxxxxxxxxxxxxxx

4. Important : Stockez votre secret en lieu sûr — vous en aurez besoin pour la vérification des requêtes

Comment fonctionne la vérification de signature

Lorsqu'elle est configurée, Koncile inclut deux en-têtes supplémentaires avec chaque requête :

En-tête	Description
X-Koncile-Signature	Signature HMAC-SHA256 du payload
X-Koncile-Timestamp	Timestamp Unix au moment de la signature de la requête

Le calcul de la signature :

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

Où {payload} représente le corps JSON brut avec un minimum d'espaces.

Vérifier les signatures

Pour valider une requête webhook :

1. Extrayez les en-têtes X-Koncile-Signature et X-Koncile-Timestamp

2. Vérifiez la récence du timestamp (dans les 5 minutes) pour prévenir les attaques par rejeu

3. Calculez la signature attendue en utilisant votre secret

4. Comparez la signature calculée avec la signature reçue

Exemples d'implémentation

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"Webhook reçu pour la tâche {task_id} : {status} - {document_name}")

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

    return {"status": "received"}

Exécuter avec :

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

Node.js

Gérer plusieurs Webhooks

Créez plusieurs webhooks pour différents scénarios :

• Développement vs Production : Webhooks séparés pour les environnements de staging et production

• Spécifique par département : Router les factures vers les systèmes comptables et les contrats vers les systèmes juridiques

• Endpoints de secours : Configurer plusieurs webhooks pour la redondance

Chaque webhook fonctionne indépendamment — les documents peuvent déclencher plusieurs webhooks s'ils correspondent à leurs critères de filtrage.

Dépannage

Le webhook ne se déclenche pas

• Confirmez l'activation du webhook (toggle activé)

• Vérifiez que les critères de filtrage correspondent aux documents traités

• Assurez-vous que l'endpoint retourne un code de statut 2xx

Erreurs de signature invalide

• Confirmez l'utilisation correcte du signing secret

• Vérifiez que le timestamp n'a pas expiré (requêtes de plus de 5 minutes rejetées)

• Assurez-vous que le calcul de la signature utilise le corps JSON brut avec un minimum d'espaces

Données manquantes dans le payload

• Confirmez que le traitement du document est terminé (le statut devrait être DONE)

• Vérifiez que le Template du document contient la configuration des Fields attendue