Webhooks

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

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

배치 웹훅 등록

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

매개변수

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

전달된 이벤트 페이로드

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

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

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

가능한 오류

• 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")