Webhooks

Registrieren Sie eine URL, die aufgerufen wird, wenn ein Batch die Verarbeitung abgeschlossen hat, oder listen Sie den persistierten Ereignisfeed für Polling-Integrationen wie Zapier-Trigger auf. Informationen zur Callback-Payload-Struktur, den drei Signatur-Headern und dem Wiederholungsplan finden Sie im Webhooks-Leitfaden — einschließlich der Tatsache, dass das erneute Verarbeiten eines Batches (Hochladen und Verarbeiten weiterer Dokumente in einen batch_name, der Sie bereits einmal benachrichtigt hat) automatisch eine eigene, separate Benachrichtigung erhält, ohne dass an diesem Endpunkt etwas getan werden muss.

Es gibt keine separate Registrierung für den Abschluss von 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 (oder unterstützt) keinen eigenen Webhook-Endpunkt. Siehe den Webhooks-Leitfaden für die Ereignis-Payload-Struktur und den Zustellungshinweis speziell für bbox.

Batch-Webhook registrieren

Erstellt oder aktualisiert den Abschluss-Callback für einen Batch. Sie können webhook_url auch direkt bei Start processing a batch angeben, um ihn im selben Aufruf zu registrieren – dieser Endpoint dient der separaten Registrierung (oder Änderung), z. B. bevor Sie bereit sind, process aufzurufen, oder um eine fehlerhafte URL im Nachhinein zu korrigieren.

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

Parameter

Name	Ort	Typ	Beschreibung
`batch_name`	Pfad	string	Der Batch, dem dieser Callback zugeordnet wird. Es müssen noch keine Dokumente hochgeladen sein – Sie können einen Webhook auch vor dem Upload registrieren.
`callback_url`	Body (JSON)	string	Erforderlich. Muss `http://` oder `https://` sein. Wird einmal aufgerufen, sobald jedes Dokument im Batch einen Endstatus erreicht.

webhook_secret wird in jeder erfolgreichen Antwort zurückgegeben – bei der ersten Registrierung und bei jeder weiteren Aktualisierung – und wird nach dem ersten Aufruf nicht maskiert. Es gibt keinen separaten GET für diese Ressource. Daher ist das erneute PUT mit derselben callback_url der unterstützte Weg, 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 erneute Scharfschalten von fired_at für eine neue Welle erfolgt stattdessen automatisch bei Start processing a batch, sobald dort neue berechtigte Dokumente in einem Batch gefunden werden, dessen vorherige Welle bereits ausgelöst wurde – siehe Abschnitt „Reprocessing a batch" im Webhooks-Leitfaden. Ein erneutes PUT auf diesen Endpoint führt für sich genommen nicht zu einer erneuten Benachrichtigung.

Zugestellte Ereignis-Payloads

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

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

{
  "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 Bbox-Annotationsauftrag, der für ein Dokument in diesem Batch ausgelöst wurde, abgeschlossen ist:

{
  "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 nach Erhalt des entsprechenden Ereignisses GET /batches/{batch_name}/results oder GET /documents/{document_id}/bbox auf, um die tatsächlichen Daten abzurufen. Beide Ereignisse werden pro Abschluss höchstens einmal zugestellt, auch wenn mehrere Dokumente (oder mehrere Bbox-Zeilengruppen) innerhalb kurzer Zeit einen Endstatus erreichen — siehe Webhooks-Leitfaden für die Signatur-Header und den Wiederholungszeitplan.

Ereignisse auflisten

Gibt einen persistenten, neueste-zuerst-Ereignisfeed für Polling-Integrationen zurück. Dies ist der richtige Endpunkt für Zapier-Polling-Trigger wie „Neuer abgeschlossener Batch", „Neues abgeschlossenes Dokument" und „Fehlgeschlagene Extraktion" — er erfordert nicht, dass Benutzer manuell einen batch_name in den Trigger eingeben.

GET /api/v1/events

Parameter

Name	Ort	Typ	Beschreibung
`type`	query, optional	string	Einer von `batch.completed`, `document.completed`, `document.failed`.
`limit`	query, optional	integer	1-100. Standard 20.
`page_token`	query, optional	string	Undurchsichtiger Cursor aus dem `next_page_token` einer vorherigen Antwort.
`batch_name`	query, optional	string	Ereignisse auf einen Batch beschränken.
`document_id`	query, optional	string	Ereignisse auf ein Dokument beschränken.
`created_from`	query, optional	datetime	Ereignisse zurückgeben, die an oder nach diesem ISO-8601-Zeitstempel erstellt wurden.
`created_to`	query, optional	datetime	Ereignisse zurückgeben, die an oder vor diesem ISO-8601-Zeitstempel erstellt wurden.

Ereignisse werden erst erstellt, nachdem der Worker den endgültigen Dokumentstatus festgeschrieben hat. Sobald ein Ereignis hier erscheint, sind seine document_url-, batch_url- und batch_results_url-Ziele sicher lesbar. Verwenden Sie id als Schlüssel zur Deduplizierung. Wenn ein fehlgeschlagenes Dokument erneut verarbeitet wird und wieder einen endgültigen Status erreicht, oder ein abgeschlossener Batch später eine weitere verarbeitete Welle erhält, erhält der neue Abschluss eine neue Ereignis-id.

Mögliche Fehler

missing_api_key / invalid_api_key / plan_required — siehe Fehlerbehandlung.
invalid_parameter — ungültiges type, limit, page_token, batch_name, created_from oder created_to.

Mögliche Fehler

missing_api_key / invalid_api_key / plan_required — siehe Fehlerbehandlung.
missing_parameter (param: "callback_url")
invalid_parameter (param: "callback_url") — keine http:///https://-URL.
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 }