웹훅

배치 처리가 완료될 때 호출할 URL을 등록하거나, Zapier 트리거와 같은 폴링 통합을 위해 저장된 이벤트 피드를 나열합니다. 콜백 페이로드 형식, 세 가지 서명 헤더 및 재시도 일정에 대한 자세한 내용은 웹훅 가이드를 참조하세요 — 여기에는 배치 재처리가 이 엔드포인트에서 별도의 조치 없이 자동으로 고유한 알림을 받는 방법도 포함됩니다.

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

배치 웹훅 등록

단일 배치에 대한 완료 콜백을 생성하거나 업데이트합니다. 배치 처리 시작 시 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를 호출하여 실제 데이터를 가져오세요. 여러 문서가 거의 동시에 최종 상태에 도달하더라도 두 이벤트 모두 완료당 최대 한 번만 전달됩니다. 서명 헤더 및 재시도 일정은 웹훅 가이드를 참조하세요.

이벤트 목록

폴링 통합을 위한 영구 저장된 최신순 이벤트 피드를 반환합니다. 이는 "새 완료 배치", "새 완료 문서", "추출 실패"와 같은 Zapier 폴링 트리거에 적합한 엔드포인트이며, 사용자가 트리거에 batch_name을 직접 입력할 필요가 없습니다.

매개변수

이벤트는 작업자가 최종 문서 상태를 커밋한 후에만 생성되므로, 이벤트가 여기에 표시될 때쯤이면 해당 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")