リファレンス

Webhooks

バッチの処理が完了したときに呼び出されるURLを登録します。バッチステータスの取得をポーリングする代わりにご利用いただけます。このページでは登録エンドポイントについて説明します。ペイロードの形式、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を再設定するには、バッチ処理の開始で自動的に行われます。前回のウェーブがすでに発火したバッチに新しい対象ドキュメントが見つかった瞬間に実行されます。詳細はWebhookガイドの「バッチの再処理」セクションを参照してください。このエンドポイントを再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ガイドを参照してください。

発生する可能性のあるエラー

  • 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]