Aperçu des Webhooks

Recevez des notifications en temps réel sur les événements de votre compte Parsurai.

Les webhooks Parsurai permettent à votre application de recevoir des notifications HTTP POST en temps réel lorsque des événements surviennent sur votre compte, par exemple lorsqu'une extraction de facture est terminée ou qu'une session de vérification manuelle est finalisée.

Types d'Événements Supportés

Type d'Événement	Description
`extraction.completed`	Un document de facture a été traité avec succès et les données structurées ont été extraites.
`extraction.failed`	Le traitement d'un document de facture a échoué en raison d'une erreur d'analyse ou d'une mise en page illisible.
`review.required`	Une vérification manuelle est requise car la confiance de l'extraction est inférieure au seuil défini.
`review.completed`	Un réviseur humain a terminé la vérification manuelle et finalisé les champs de la facture.
`workflow.completed`	L'ensemble du pipeline de traitement (y compris le recadrage, le fractionnement et la révision optionnels) a réussi.
`workflow.failed`	Le pipeline a été abandonné en raison de l'échec de l'une des étapes de traitement obligatoires.

Structure du Payload (Enveloppe)

Tous les webhooks sont envoyés sous forme de requêtes HTTP POST au format application/json. Le corps de la requête contient un objet JSON enveloppant les métadonnées de l'événement et les données spécifiques de la ressource.

{
  "id": "evt_9f3b2c1d0e4a4f5b8c6d7e8f9a0b1c2d",
  "type": "extraction.completed",
  "version": "2026-06-01",
  "occurred_at": "2026-06-21T10:40:00Z",
  "tenant_id": "7f9c2f4e-9b1a-4c3d-8e5f-6a7b8c9d0e1f",
  "data": {
    "invoice_id": "a3a4c1de-1c1e-4b6f-9d2a-0f8e7d6c5b4a"
  }
}

Champs Principaux

id : Un identifiant unique pour cet événement (evt_...). Utilisé pour la déduplication.
type : Le type d'événement (par exemple extraction.completed).
version : La version de l'enveloppe de l'API correspondant à la configuration de l'utilisateur.
occurred_at : Horodatage ISO-8601 UTC de l'événement original.
tenant_id : L'identifiant de votre compte/tenant Parsurai.
data : Un objet de données contenant les références ou métadonnées pertinentes pour l'événement. Pour protéger les données sensibles de nos clients, les payloads des webhooks minimisent les informations personnelles (PII) et ne contiennent que les identifiants des ressources. Vous pouvez obtenir les détails complets de la ressource en interrogeant notre API REST ou nos SDK.

Politiques de Livraison & Sécurité

Protocole HTTPS : En production, Parsurai livre uniquement les webhooks à des URL sécurisées de type https://.
Restriction de Port : Les points de terminaison de production doivent écouter sur le port 443 (explicitement ou implicitement). Les autres ports seront rejetés afin d'éviter les attaques de type Server-Side Request Forgery (SSRF).
Pas d'adresses IP Statiques : Parsurai n'envoie pas ses webhooks depuis un bloc d'adresses IP statiques. Vous devez valider les signatures des requêtes plutôt que de mettre en liste blanche des adresses IP.
Délai d'Attente (Timeout) : Nous attendons de votre serveur qu'il réponde avec un code d'état 2xx en moins de 10 secondes (connexion/lecture). Dans le cas contraire, une tentative de renvoi sera initiée.
Historique après Suppression : Lorsqu'un point de terminaison de webhook est supprimé, il est marqué comme supprimé de manière logique (soft-delete). L'historique des livraisons est conservé pour audit jusqu'à la fin de la période de rétention.
Idempotence : Les webhooks sont livrés au moins une fois. Votre serveur de réception doit être idempotent en vérifiant le champ id avant de traiter les événements.