Webhooks

Enregistrez une URL à appeler lorsqu'un lot termine son traitement, ou listez le flux d'événements persisté pour les intégrations par interrogation telles que les déclencheurs Zapier. Pour la structure du payload de rappel, les trois en-têtes de signature et le calendrier de nouvelle tentative, consultez le guide Webhooks — y compris comment le retraitement d'un lot (téléversement et traitement de documents supplémentaires dans un batch_name qui vous a déjà notifié une fois) reçoit automatiquement sa propre notification distincte, sans action requise sur cet endpoint.

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 endpoint webhook. Consultez le guide Webhooks pour la structure du payload d'événement et l'avertissement de livraison spécifique à bbox.

Enregistrer un webhook de lot

Crée ou met à jour le callback de fin 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 — cet endpoint existe pour l'enregistrer (ou le modifier) séparément, par exemple avant d'être prêt à appeler process, ou pour corriger une URL avec une faute de frappe par la suite.

PUT /api/v1/batches/{batch_name}/webhook

Paramètres

Nom	Emplacement	Type	Description
`batch_name`	chemin	string	Le lot auquel attacher ce callback. Il n'est pas nécessaire que des documents y soient déjà téléversés — vous pouvez enregistrer un webhook avant le téléversement.
`callback_url`	corps (JSON)	string	Requis. Doit être `http://` ou `https://`. Appelé une fois, lorsque chaque document du lot atteint un statut terminal.

webhook_secret est renvoyé dans chaque réponse réussie — lors du premier enregistrement et à chaque mise à jour ultérieure — non masqué après le premier appel. Il n'existe pas de GET séparé pour cette ressource, donc un nouveau PUT avec le 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 qu'à callback_url : webhook_secret n'est jamais réinitialisé par cet appel, et fired_at (si la vague de traitement la plus récente de ce lot vous a déjà notifié) n'est jamais réinitialisé par cet appel. Le réarmement de fired_at pour une nouvelle vague se fait sur Démarrer le traitement d'un lot à la place, automatiquement, dès qu'il 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 Webhooks. Un nouveau PUT sur cet endpoint ne vous permet pas en soi d'être notifié à nouveau.

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 de niveau supérieur "type" — ce point de terminaison ne renvoie jamais l'une ou l'autre forme ; 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 des deux charges utiles 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 plus une fois par achèvement, même lorsque plusieurs documents (ou plusieurs groupes de lignes bbox) atteignent un statut terminal à quelques instants d'intervalle — voir le guide des webhooks pour les en-têtes de signature et le calendrier de nouvelle tentative.

Lister les événements

Renvoie un flux d'événements persisté, du plus récent au plus ancien, pour les intégrations par interrogation. C'est le point de terminaison adapté aux déclencheurs d'interrogation Zapier tels que « Nouveau lot terminé », « Nouveau document terminé » et « Extraction échouée » — il ne nécessite pas que les utilisateurs saisissent manuellement un batch_name dans le déclencheur.

GET /api/v1/events

Paramètres

Nom	Emplacement	Type	Description
`type`	query, facultatif	string	L'un des suivants : `batch.completed`, `document.completed`, `document.failed`.
`limit`	query, facultatif	integer	1-100. Par défaut : 20.
`page_token`	query, facultatif	string	Curseur opaque provenant du `next_page_token` d'une réponse précédente.
`batch_name`	query, facultatif	string	Restreindre les événements à un seul lot.
`document_id`	query, facultatif	string	Restreindre les événements à un seul document.
`created_from`	query, facultatif	datetime	Renvoie les événements créés à partir de cet horodatage ISO 8601 inclus.
`created_to`	query, facultatif	datetime	Renvoie les événements créés jusqu'à cet horodatage ISO 8601 inclus.

Les événements ne sont créés qu'après que le worker a validé l'état final du document. Ainsi, lorsqu'un événement apparaît ici, ses cibles document_url, batch_url et batch_results_url sont sûres à lire. Utilisez id comme clé de déduplication. Si un document en échec est retraité et atteint à nouveau un état final, ou si un lot terminé reçoit ensuite une nouvelle vague de traitement, la nouvelle finalisation reçoit un nouvel id d'événement.

Erreurs possibles

missing_api_key / invalid_api_key / plan_required — voir Gestion des erreurs.
invalid_parameter — type, limit, page_token, batch_name, created_from ou created_to invalide.

Erreurs possibles

missing_api_key / invalid_api_key / plan_required — voir Gestion des erreurs.
missing_parameter (param: "callback_url")
invalid_parameter (param: "callback_url") — ce n'est pas une URL http:///https://.
invalid_parameter (param: "batch_name")

curl -X PUT https://imagetotable.ai/api/v1/batches/july-invoices/webhook \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{"callback_url": "https://example.com/webhooks/imagetotable"}'

import os import requests response = requests.put( "https://imagetotable.ai/api/v1/batches/july-invoices/webhook", headers={"Authorization": f"Bearer {os.environ['API_KEY']}"}, json={"callback_url": "https://example.com/webhooks/imagetotable"}, ) print(response.json())

const response = await fetch("https://imagetotable.ai/api/v1/batches/july-invoices/webhook", { method: "PUT", headers: { "Authorization": `Bearer ${process.env.API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ callback_url: "https://example.com/webhooks/imagetotable" }), }); console.log(await response.json());

{ "batch_name": "july-invoices", "callback_url": "https://example.com/webhooks/imagetotable", "webhook_secret": "9f2c1e6a4b8d0f37c5a2e9d1b6f4038a7c1e5d29b4f81c62", "created_at": "2026-07-16T09:00:00+00:00", "fired_at": null }

import os import requests response = requests.get( "https://imagetotable.ai/api/v1/events", headers={"Authorization": f"Bearer {os.environ['API_KEY']}"}, params={"type": "batch.completed", "limit": 20}, ) print(response.json())

{ "events": [ { "id": "evt_3f9c9e2a1b7d4e2b9a3e2f5b6c7d8e9f", "type": "batch.completed", "created_at": "2026-08-04T08:31:22+00:00", "batch_name": "260804-4K9P", "document_id": null, "status": "succeeded", "document_count": 3, "filename": null, "error": null, "batch_url": "https://imagetotable.ai/api/v1/batches/260804-4K9P", "batch_results_url": "https://imagetotable.ai/api/v1/batches/260804-4K9P/results" } ], "has_more": false, "next_page_token": null }