Webhooks

Registrieren Sie eine URL, die aufgerufen wird, wenn ein Batch die Verarbeitung abgeschlossen hat, oder listen Sie den persistierten Ereignis-Feed 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 die erneute Verarbeitung eines Batches (das 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 eine Aktion erforderlich ist.

Es gibt keine separate Registrierung für den Abschluss von bbox. Die gleiche callback_url, die Sie hier registrieren, empfängt auch ein document.bbox_completed-Ereignis, wenn ein bbox-Annotationsauftrag für ein Dokument in diesem Batch abgeschlossen wird — das Auslösen von bbox erfordert keinen (und unterstützt keinen) eigenen Webhook-Endpunkt. Siehe den Webhooks- Leitfaden für die Ereignis-Payload-Struktur und den spezifischen Zustellhinweis 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 dazu, ihn separat zu registrieren (oder zu ändern), z. B. bevor Sie bereit sind, process aufzurufen, oder um eine fehlerhafte URL später zu korrigieren.

Parameter

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-Endpoint für diese Ressource. Daher ist das erneute PUT mit derselben callback_url der unterstützte Weg, um Ihr Secret erneut 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 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 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 Feld "type" unterscheiden — dieser Endpunkt selbst gibt keine der beiden Formen zurück; das ist es, 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 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 GET /batches/{batch_name}/results oder GET /documents/{document_id}/bbox auf, nachdem Sie das entsprechende Ereignis empfangen haben, um die tatsächlichen Daten abzurufen. Beide Ereignisse werden höchstens einmal pro Abschluss zugestellt, selbst wenn mehrere Dokumente (oder mehrere Bbox-Zeilengruppen) innerhalb von Augenblicken einen Endstatus erreichen — siehe Webhook-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.

Parameter

Ereignisse werden erst erstellt, nachdem der Worker den endgültigen Dokumentzustand festgeschrieben hat. Sobald ein Ereignis hier erscheint, sind seine document_url-, batch_url- und batch_results_url- Ziele sicher lesbar. Verwenden Sie id als Deduplizierungsschlüssel. Wenn ein fehlgeschlagenes Dokument erneut verarbeitet wird und wieder einen endgültigen Zustand 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")