Webhooks

Registrieren Sie eine URL, die aufgerufen wird, wenn ein Batch die Verarbeitung abschließt, anstatt den Batch-Status abzufragen. Diese Seite behandelt den einen Registrierungsendpunkt; für die Payload-Struktur, die drei Signatur-Header und den Wiederholungsplan siehe das Webhooks-Handbuch – 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. 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 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 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.

Parameter

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, 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. 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:

{
  "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, der für ein Dokument in diesem Batch gestartet 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 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 für die Signatur-Header und den Wiederholungsplan.

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")