リファレンス

Webhooks

バッチの処理が完了したときに呼び出されるURLを登録するか、Zapierトリガーなどのポーリング統合用に保存されたイベントフィードを一覧表示します。コールバックのペイロード形式、3つの署名ヘッダー、再試行スケジュールについては、Webhooksガイドを参照してください。特に、バッチの再処理（すでに通知済みのbatch_nameにドキュメントを追加アップロードして処理する場合）では、このエンドポイントでの操作を必要とせず、自動的に別の通知が送信されます。

bbox完了のための個別登録は不要です。ここで登録した同じcallback_urlが、このバッチ内の任意のドキュメントでbboxアノテーションジョブが完了するたびにdocument.bbox_completedイベントも受け取ります。bboxのトリガーには独自のWebhookエンドポイントは不要（および非対応）です。イベントのペイロード形式とbbox固有の配信に関する注意事項については、Webhooksガイドを参照してください。

バッチWebhookを登録する

1つのバッチに対する完了コールバックを作成または更新します。webhook_urlを バッチ処理を開始で直接設定して、同じ呼び出しで登録することもできます。このエンドポイントは、processを呼び出す準備ができる前などに、別途登録（または変更）するためのものです。後でURLのタイプミスを修正する場合にも使用できます。

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

パラメータ

名前場所型説明
batch_nameパスstringこのコールバックを紐付けるバッチ。ドキュメントがアップロード済みである必要はありません。アップロード前にWebhookを登録できます。
callback_urlボディ（JSON）string必須。http://またはhttps://である必要があります。バッチ内のすべてのドキュメントが最終ステータスに達したときに1回呼び出されます。

webhook_secretは、すべての成功レスポンスで返されます — 初回登録時も、その後の更新時も同様で、初回呼び出し後にマスクされることはありません。このリソースには個別のGETがないため、同じcallback_urlを再PUTすることが、シークレットを紛失した場合に再取得するためのサポートされた方法です。既存の登録を更新しても、callback_urlのみが変更されます。webhook_secretがこの呼び出しでローテーションされることはなく、fired_at（このバッチの最新の処理ウェーブがすでに通知済みかどうか）もこの呼び出しでリセットされることはありません。新しいウェーブのためにfired_atを再設定するには、バッチ処理を開始で自動的に行われます。前のウェーブがすでに発火したバッチで新しい対象ドキュメントが見つかった瞬間に実行されます — Webhooksガイドの「バッチの再処理」セクションを参照してください。このエンドポイントを再PUTしても、それ自体では再度通知を受けることはできません。

配信されるイベントペイロード

登録すると、callback_url は2種類のイベントタイプのいずれかに対して POST を受信します。これらはトップレベルの "type" フィールドで区別されます。このエンドポイント自体はどちらの形式も返しません。これらはあなたのサーバーが受信するものです。

batch.completed — バッチ内のすべてのドキュメントが最終ステータスに達したときに1回だけ発火します：

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

document.bbox_completed — このバッチ内の任意のドキュメントでトリガーされたbboxアノテーションジョブが完了したときに発火します：

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

どちらのペイロードも抽出結果自体は含まれません。対応するイベントを受信した後、GET /batches/{batch_name}/results または GET /documents/{document_id}/bbox を呼び出して実際のデータを取得してください。両方のイベントは、複数のドキュメント（または複数のbbox行グループ）がほぼ同時に最終ステータスに達した場合でも、完了ごとに最大1回配信されます。署名ヘッダーと再試行スケジュールについてはWebhookガイドを参照してください。

イベント一覧

ポーリング統合用に、永続化された新しい順のイベントフィードを返します。これはZapierのポーリングトリガー（「新規完了バッチ」「新規完了ドキュメント」「抽出失敗」など）に適したエンドポイントです。ユーザーがトリガーに batch_name を手入力する必要はありません。

GET /api/v1/events

パラメータ

名前場所型説明
typeクエリ、任意文字列batch.completed、document.completed、document.failed のいずれか。
limitクエリ、任意整数1〜100。デフォルトは20。
page_tokenクエリ、任意文字列前回のレスポンスの next_page_token からの不透明なカーソル。
batch_nameクエリ、任意文字列イベントを1つのバッチに限定します。
document_idクエリ、任意文字列イベントを1つのドキュメントに限定します。
created_fromクエリ、任意日時このISO 8601タイムスタンプ以降に作成されたイベントを返します。
created_toクエリ、任意日時このISO 8601タイムスタンプ以前に作成されたイベントを返します。

イベントは、ワーカーが最終的なドキュメント状態を確定した後にのみ作成されます。そのため、イベントがここに表示される時点で、その document_url、batch_url、batch_results_url のターゲットは安全に読み取れます。id を重複排除キーとして使用してください。失敗したドキュメントが再処理されて再び最終状態に達した場合、または完了したバッチに後から別の処理ウェーブが追加された場合、新しい完了には新しいイベント id が付与されます。

考えられるエラー

  • missing_api_key / invalid_api_key / plan_required — エラーハンドリング を参照してください。
  • invalid_parameter — type、limit、page_token、batch_name、created_from、または created_to が不正です。

発生しうるエラー

  • missing_api_key / invalid_api_key / plan_required — エラー処理を参照してください。
  • missing_parameter (param: "callback_url")
  • invalid_parameter (param: "callback_url") — http:///https://のURLではありません。
  • invalid_parameter (param: "batch_name")
📮 contact email: [email protected]