リファレンス

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 を呼び出して実際のデータを取得してください。両方のイベントは、完了ごとに最大1回配信されます。複数のドキュメント（または複数のbbox行グループ）がほぼ同時に最終ステータスに達した場合でも同様です。署名ヘッダーと再試行スケジュールについてはWebhookガイドを参照してください。

イベント一覧

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

GET /api/v1/events

パラメータ

名前場所型説明
typeクエリ、任意stringbatch.completed、document.completed、document.failedのいずれか。
limitクエリ、任意integer1〜100。デフォルトは20。
page_tokenクエリ、任意string前回のレスポンスのnext_page_tokenからの不透明なカーソル。
batch_nameクエリ、任意stringイベントを1つのバッチに限定します。
document_idクエリ、任意stringイベントを1つのドキュメントに限定します。
created_fromクエリ、任意datetimeこのISO 8601タイムスタンプ以降に作成されたイベントを返します。
created_toクエリ、任意datetimeこの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]