# Webhooks APIリファレンス — コールバックURLとシークレット

> バッチの完了コールバックURLを登録・更新し、署名シークレットを取得します — ImageToTable.ai v1 APIのWebhooksリファレンスです。

バッチの処理が完了したときに呼び出されるURLを登録します。[バッチステータスの取得](/developers/reference/batches#get-batch-status)をポーリングする代わりにご利用いただけます。このページでは登録エンドポイントについて説明します。ペイロードの形式、3つの署名ヘッダー、リトライスケジュールについては、[Webhooksガイド](/developers/guides/webhooks)をご覧ください。なお、**バッチの再処理**（既に通知済みの`batch_name`にさらにドキュメントをアップロード・処理する場合）では、このエンドポイントでの操作を必要とせず、自動的に別個の通知が送信されます。

**[bbox](/developers/guides/bbox)完了のための個別登録は不要です。**ここで登録した`callback_url`は、このバッチ内のいずれかのドキュメントでbboxアノテーションジョブが完了した際にも`document.bbox_completed`イベントを受け取ります。bboxのトリガーには専用のWebhookエンドポイントは必要ありません（対応もしていません）。イベントペイロードの形式と、bboxに固有の配信に関する注意点については、[Webhooksガイド](/developers/guides/webhooks)をご覧ください。

## バッチWebhookの登録

1つのバッチの完了コールバックを作成または更新します。`webhook_url`は[バッチ処理の開始](/developers/reference/batches#start-processing-a-batch)で直接設定し、同じ呼び出しで登録することもできます。このエンドポイントは、例えば`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`を再設定するには、[バッチ処理の開始](/developers/reference/batches#start-processing-a-batch)で自動的に行われます。前回のウェーブがすでに発火したバッチに新しい対象ドキュメントが見つかった瞬間に実行されます。詳細は[Webhookガイド](/developers/guides/webhooks)の「バッチの再処理」セクションを参照してください。このエンドポイントを再`PUT`しても、それだけで再度通知されるわけではありません。

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

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

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

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

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

```json
{
  "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ガイド](/developers/guides/webhooks)を参照してください。

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

- `missing_api_key` / `invalid_api_key` / `plan_required` — [エラーハンドリング](/developers/guides/errors)を参照してください。
- `missing_parameter` (`param: "callback_url"`)
- `invalid_parameter` (`param: "callback_url"`) — `http://`/`https://` URLではありません。
- `invalid_parameter` (`param: "batch_name"`)

## Code Examples

### バッチWebhookの登録

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

**cURL**

```bash
curl -X PUT https://imagetotable.ai/api/v1/batches/july-invoices/webhook \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"callback_url": "https://example.com/webhooks/imagetotable"}'
```

**Python**

```python
import os
import requests

response = requests.put(
    "https://imagetotable.ai/api/v1/batches/july-invoices/webhook",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
    json={"callback_url": "https://example.com/webhooks/imagetotable"},
)
print(response.json())
```

**Javascript**

```javascript
const response = await fetch("https://imagetotable.ai/api/v1/batches/july-invoices/webhook", {
  method: "PUT",
  headers: {
    "Authorization": `Bearer ${process.env.API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ callback_url: "https://example.com/webhooks/imagetotable" }),
});
console.log(await response.json());
```

### レスポンス

```json
{
  "batch_name": "july-invoices",
  "callback_url": "https://example.com/webhooks/imagetotable",
  "webhook_secret": "9f2c1e6a4b8d0f37c5a2e9d1b6f4038a7c1e5d29b4f81c62",
  "created_at": "2026-07-16T09:00:00+00:00",
  "fired_at": null
}
```

`webhook_secret`は、同じ`batch_name`に対してこのエンドポイントを繰り返し呼び出しても変わりません。初回登録時に一度だけ生成されます。`fired_at`は、このバッチの完了通知が初めて（そして唯一）配信されたときに`null`からタイムスタンプに変わります。

---

Source: https://imagetotable.ai/ja/developers/reference/webhooks