# Webhooks API 참조 — 콜백 URL 및 시크릿

> 배치의 완료 콜백 URL을 등록 또는 업데이트하고 서명 시크릿을 조회합니다 — ImageToTable.ai v1 API의 Webhooks 참조입니다.

배치 처리가 완료될 때 호출할 URL을 등록합니다. [배치 상태 조회](/developers/reference/batches#get-batch-status)를 폴링하는 대신 사용할 수 있습니다. 이 페이지는 등록 엔드포인트 하나를 다룹니다. 페이로드 형식, 세 가지 서명 헤더, 재시도 일정에 대해서는 [Webhooks 가이드](/developers/guides/webhooks)를 참조하세요. 여기에는 **배치 재처리** 시 별도의 알림이 자동으로 전송되며, 이 엔드포인트에서 추가 작업이 필요하지 않다는 내용도 포함됩니다.

**[bbox](/developers/guides/bbox) 완료를 위한 별도 등록은 없습니다.** 여기에 등록한 동일한 `callback_url`이 이 배치 내 문서의 bbox 주석 작업이 완료될 때마다 `document.bbox_completed` 이벤트도 수신합니다. bbox를 트리거하는 데 자체 webhook 엔드포인트가 필요하지 않으며 지원되지도 않습니다. 이벤트 페이로드 형식과 bbox 특정 전달 주의사항은 [Webhooks 가이드](/developers/guides/webhooks)를 참조하세요.

## 배치 웹훅 등록

하나의 배치에 대한 완료 콜백을 생성하거나 업데이트합니다. [배치 처리 시작](/developers/reference/batches#start-processing-a-batch)에서 `webhook_url`을 직접 설정하여 동일한 호출에서 등록할 수도 있습니다. 이 엔드포인트는 별도로 등록하기 위해 존재합니다. 예를 들어 `process`를 호출할 준비가 되기 전에, 또는 이후에 잘못 입력된 URL을 수정하기 위해 사용할 수 있습니다.

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

### 매개변수

| 이름 | 위치 | 유형 | 설명 |
| --- | --- | --- | --- |
| batch_name | path | string | 이 콜백을 연결할 배치입니다. 문서가 이미 업로드되어 있을 필요는 없습니다. 업로드 전에 웹훅을 미리 등록할 수 있습니다. |
| callback_url | body (JSON) | string | 필수입니다. http:// 또는 https:// 여야 합니다. 배치 내 모든 문서가 최종 상태에 도달하면 한 번 호출됩니다. |

**`webhook_secret`은 모든 성공 응답에 반환됩니다** — 첫 등록 시와 이후 모든 업데이트 시 모두, 첫 호출 후 마스킹되지 않습니다. 이 리소스에 대한 별도의 `GET`은 없으므로, 동일한 `callback_url`로 다시 `PUT`하는 것이 비밀번호를 분실했을 때 다시 검색하는 지원되는 방법입니다. 기존 등록을 업데이트하면 `callback_url`만 변경됩니다. `webhook_secret`은 이 호출로 절대 교체되지 않으며, `fired_at`도 이 호출로 재설정되지 않습니다. 새로운 웨이브를 위해 `fired_at`을 재설정하는 것은 [배치 처리 시작](/developers/reference/batches#start-processing-a-batch)에서 자동으로 이루어집니다. 이전 웨이브가 이미 실행된 배치에서 새로운 적격 문서를 찾는 즉시 수행됩니다. 자세한 내용은 [웹훅 가이드](/developers/guides/webhooks)의 "배치 재처리" 섹션을 참조하세요. 이 엔드포인트를 다시 `PUT`한다고 해서 자동으로 다시 알림을 받지는 않습니다.

### 전달된 이벤트 페이로드

등록되면 `callback_url`은 두 가지 이벤트 유형 중 하나에 대해 `POST`를 수신합니다. 이 유형은 최상위 `"type"` 필드로 구분됩니다. 이 엔드포인트 자체는 어떤 형태도 반환하지 않으며, 이는 *귀하의* 서버가 수신하는 내용입니다.

`batch.completed` — 배치 내 모든 문서가 최종 상태에 도달하면 한 번 실행됩니다:

```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`를 호출하여 실제 데이터를 가져오세요. 여러 문서가 거의 동시에 최종 상태에 도달하더라도 두 이벤트는 완료당 최대 한 번만 전달됩니다. 서명 헤더 및 재시도 일정은 [웹훅 가이드](/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

### 배치 웹훅 등록

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
}
```

동일한 `batch_name`에 대해 이 엔드포인트를 반복 호출해도 `webhook_secret`은 변경되지 않습니다. 최초 등록 시 한 번만 생성됩니다. `fired_at`은 이 배치의 완료 알림이 전달되는 첫 번째 시점에 `null`에서 타임스탬프로 변경됩니다.

---

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