# Référence API Webhooks — URL de rappel et secrets

> Enregistrez ou mettez à jour l'URL de rappel de fin de traitement d'un lot, et récupérez son secret de signature — la référence Webhooks de l'API v1 d'ImageToTable.ai.

Enregistrez une URL à appeler lorsqu'un lot termine son traitement, au lieu d'interroger [Obtenir le statut du lot](/developers/reference/batches#get-batch-status). 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](/developers/guides/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](/developers/guides/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](/developers/guides/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](/developers/reference/batches#start-processing-a-batch) 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.

`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 soient déjà téléchargés — vous pouvez enregistrer un webhook avant le téléchargement. |
| 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 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](/developers/reference/batches#start-processing-a-batch), 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](/developers/guides/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 :

```json
{
  "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](/developers/guides/bbox) déclenché sur un document de ce lot se termine :

```json
{
  "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](/developers/guides/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](/developers/guides/errors).
- `missing_parameter` (`param: "callback_url"`)
- `invalid_parameter` (`param: "callback_url"`) — URL non `http://`/`https://`.
- `invalid_parameter` (`param: "batch_name"`)

## Code Examples

### Enregistrer un webhook de lot

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

**cURL**

```bash
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"}'
```

**Python**

```python
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())
```

**Javascript**

```javascript
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());
```

### Réponse

```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
}
```

`webhook_secret` reste identique lors d'appels répétés à ce point de terminaison pour le même `batch_name` — il n'est généré qu'une seule fois, lors du premier enregistrement. `fired_at` passe de `null` à un horodatage la première (et unique) fois que la notification d'achèvement de ce lot est délivrée.

---

Source: https://imagetotable.ai/fr/developers/reference/webhooks