Webhooks

Enregistrez une URL à appeler lorsqu'un lot termine son traitement, au lieu d'interroger Obtenir le statut du lot. Cette page couvre le point d'accès d'enregistrement unique ; pour la structure de la charge utile, les trois en-têtes de signature et le calendrier des tentatives, consultez le Guide Webhooks — y compris comment le retraitement d'un lot (téléchargement et traitement de documents supplémentaires dans un batch_name qui vous a déjà notifié une fois) déclenche automatiquement sa propre notification distincte, sans aucune action nécessaire sur ce point d'accès.

Il n'existe pas d'enregistrement séparé pour l'achèvement bbox. La même callback_url que vous enregistrez ici reçoit également un événement document.bbox_completed chaque fois qu'un travail d'annotation bbox se termine sur un document de ce lot — le déclenchement de bbox ne nécessite pas (ni ne prend en charge) son propre point d'accès webhook. Consultez le Guide Webhooks pour la structure de la charge utile de l'événement et la mise en garde de livraison spécifique à bbox.

Enregistrer un webhook de lot

Crée ou met à jour le callback d'achèvement pour un lot. Vous pouvez également définir webhook_url directement sur Démarrer le traitement d'un lot pour l'enregistrer dans le même appel — ce point d'accès existe pour l'enregistrer (ou le modifier) séparément, par exemple avant d'être prêt à appeler process, ou pour corriger une URL erronée par la suite.

Paramètres

webhook_secret est renvoyé dans chaque réponse réussie — lors du premier enregistrement et lors de chaque mise à jour ultérieure — sans être masqué après le premier appel. Il n'existe pas de GET séparé pour cette ressource, donc ré-PUT-er la même callback_url est la méthode prise en charge pour récupérer votre secret si vous le perdez. La mise à jour d'un enregistrement existant ne touche jamais que callback_url : webhook_secret n'est jamais modifié par cet appel, et fired_at (indiquant si la dernière vague de traitement de ce lot vous a déjà notifié) n'est jamais réinitialisé par cet appel. La réinitialisation de fired_at pour une nouvelle vague se produit automatiquement sur Démarrer le traitement d'un lot, dès qu'elle trouve de nouveaux documents éligibles dans un lot dont la vague précédente a déjà été déclenchée — voir la section "Reprocessing a batch" du Guide des webhooks. Ré-PUT-er ce point d'accès ne vous permet pas d'être notifié à nouveau par lui-même.

Charges utiles des événements livrés

Une fois enregistré, callback_url reçoit un POST pour l'un des deux types d'événements, distingués par le champ "type" de premier niveau — ce point d'accès ne renvoie jamais l'une ou l'autre structure ; ce sont celles que votre serveur reçoit.

batch.completed — se déclenche une fois, lorsque chaque document du lot atteint un statut terminal :

{
  "type": "batch.completed",
  "created_at": "2026-07-16T09:14:31Z",
  "data": {
    "batch_name": "260716-4K9P",
    "status": "succeeded",
    "document_count": 3
  }
}

document.bbox_completed — se déclenche lorsqu'un travail d'annotation bbox déclenché sur un document de ce lot se termine :

{
  "type": "document.bbox_completed",
  "created_at": "2026-07-16T09:20:07Z",
  "data": {
    "document_id": "3f9c9e2a-1b7d-4e2b-9a3e-2f5b6c7d8e9f",
    "group_batch_id": "bx_8a3c2e1f",
    "status": "succeeded"
  }
}

Aucune charge utile ne contient les résultats extraits eux-mêmes — appelez GET /batches/{batch_name}/results ou GET /documents/{document_id}/bbox après avoir reçu l'événement correspondant pour récupérer les données réelles. Les deux événements sont livrés au maximum une fois par achèvement, même lorsque plusieurs documents (ou plusieurs groupes de lignes bbox) atteignent un statut terminal à quelques instants d'intervalle — consultez le Guide des webhooks pour les en-têtes de signature et le calendrier de relance.

Erreurs possibles

• missing_api_key / invalid_api_key / plan_required — voir Gestion des erreurs.
• missing_parameter (param: "callback_url")
• invalid_parameter (param: "callback_url") — URL non http:///https://.
• invalid_parameter (param: "batch_name")