# Webhooks-API-Referenz — Callback-URLs & Secrets

> Registrieren oder aktualisieren Sie die Abschluss-Callback-URL für einen Batch und rufen Sie dessen Signing-Secret ab – die Webhooks-Referenz der ImageToTable.ai v1 API.

Registrieren Sie eine URL, die aufgerufen wird, wenn ein Batch die Verarbeitung abschließt, anstatt den [Batch-Status abzufragen](/developers/reference/batches#get-batch-status). Diese Seite behandelt den einen Registrierungsendpunkt; für die Payload-Struktur, die drei Signatur-Header und den Wiederholungsplan siehe das [Webhooks-Handbuch](/developers/guides/webhooks) – einschließlich der Tatsache, dass die **Wiederholung eines Batches** (Hochladen und Verarbeiten weiterer Dokumente in einen `batch_name`, der Sie bereits benachrichtigt hat) automatisch eine eigene, separate Benachrichtigung erhält, ohne dass an diesem Endpunkt eine Aktion erforderlich ist.

**Es gibt keine separate Registrierung für den Abschluss von [Bbox](/developers/guides/bbox).** Dieselbe `callback_url`, die Sie hier registrieren, empfängt auch ein `document.bbox_completed`-Ereignis, sobald ein Bbox-Annotationsauftrag für ein Dokument in diesem Batch abgeschlossen ist – das Auslösen von Bbox erfordert (und unterstützt) keinen eigenen Webhook-Endpunkt. Siehe das [Webhooks-Handbuch](/developers/guides/webhooks) für die Ereignis-Payload-Struktur und den für Bbox spezifischen Zustellungsvorbehalt.

## Batch-Webhook registrieren

Erstellt oder aktualisiert den Abschluss-Callback für einen Batch. Sie können `webhook_url` auch direkt bei [Batch-Verarbeitung starten](/developers/reference/batches#start-processing-a-batch) angeben, um ihn im selben Aufruf zu registrieren – dieser Endpunkt dient der separaten Registrierung (oder Änderung), z. B. bevor Sie bereit sind, `process` aufzurufen, oder um eine vertippte URL nachträglich zu korrigieren.

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

### Parameter

| Name | Ort | Typ | Beschreibung |
| --- | --- | --- | --- |
| batch_name | Pfad | string | Der Batch, an den dieser Callback angehängt wird. Es müssen noch keine Dokumente hochgeladen sein – Sie können einen Webhook bereits vor dem Hochladen registrieren. |
| callback_url | Body (JSON) | string | Erforderlich. Muss http:// oder https:// sein. Wird einmal aufgerufen, wenn jedes Dokument im Batch einen Endstatus erreicht. |

**`webhook_secret` wird in jeder erfolgreichen Antwort zurückgegeben** – bei der ersten Registrierung und bei jeder späteren Aktualisierung – und wird nach dem ersten Aufruf nicht maskiert. Es gibt keinen separaten `GET`-Endpunkt für diese Ressource, daher ist ein erneutes `PUT` mit derselben `callback_url` die unterstützte Methode, um Ihr Secret wieder abzurufen, falls Sie es verlieren. Eine Aktualisierung einer bestehenden Registrierung betrifft ausschließlich `callback_url`: `webhook_secret` wird durch diesen Aufruf nie rotiert, und `fired_at` (ob die letzte Verarbeitungswelle dieses Batches Sie bereits benachrichtigt hat) wird durch diesen Aufruf nie zurückgesetzt. Das Zurücksetzen von `fired_at` für eine neue Welle erfolgt stattdessen automatisch bei [Batch-Verarbeitung starten](/developers/reference/batches#start-processing-a-batch), sobald dieser neue berechtigte Dokumente in einem Batch findet, dessen vorherige Welle bereits ausgelöst wurde – siehe den Abschnitt „Batch erneut verarbeiten“ im [Webhook-Leitfaden](/developers/guides/webhooks). Ein erneutes `PUT` auf diesen Endpunkt führt nicht dazu, dass Sie erneut benachrichtigt werden.

### Zugestellte Ereignis-Payloads

Nach der Registrierung empfängt `callback_url` einen `POST` für einen von zwei Ereignistypen, die sich durch das oberste `"type"`-Feld unterscheiden – dieser Endpunkt selbst gibt nie eine der beiden Formen zurück; dies ist, was *Ihr* Server empfängt.

`batch.completed` – wird einmal ausgelöst, wenn jedes Dokument im Batch einen Endstatus erreicht:

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

`document.bbox_completed` – wird ausgelöst, wenn ein [Bounding-Box-Annotationsauftrag](/developers/guides/bbox), der für ein Dokument in diesem Batch gestartet wurde, abgeschlossen ist:

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

Keiner der Payloads enthält die extrahierten Ergebnisse selbst – rufen Sie `GET /batches/{batch_name}/results` oder `GET /documents/{document_id}/bbox` auf, nachdem Sie das entsprechende Ereignis erhalten haben, um die tatsächlichen Daten abzurufen. Beide Ereignisse werden höchstens einmal pro Abschluss zugestellt, selbst wenn mehrere Dokumente (oder mehrere Bounding-Box-Zeilengruppen) innerhalb kurzer Zeit einen Endstatus erreichen – siehe die [Webhook-Anleitung](/developers/guides/webhooks) für die Signatur-Header und den Wiederholungsplan.

### Mögliche Fehler

- `missing_api_key` / `invalid_api_key` / `plan_required` – siehe [Fehlerbehandlung](/developers/guides/errors).
- `missing_parameter` (`param: "callback_url"`)
- `invalid_parameter` (`param: "callback_url"`) – keine `http://`/`https://`-URL.
- `invalid_parameter` (`param: "batch_name"`)

## Code Examples

### Batch-Webhook registrieren

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

### Antwort

```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` bleibt bei wiederholten Aufrufen dieses Endpunkts für denselben `batch_name` gleich – es wird nur einmal bei der ersten Registrierung generiert. `fired_at` wechselt von `null` zu einem Zeitstempel, sobald die Abschlussbenachrichtigung dieses Batches zum ersten (und einzigen) Mal zugestellt wird.

---

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