Webhooks
ATRACE Report API의 report.completed / report.failed 이벤트 알림.
리포트 처리는 비동기입니다. webhook은 이벤트 알림용입니다. 신뢰 가능한 완료 확인은 GET /reports/{id} 폴링으로 하는 것을 권장합니다.
webhook 요청에 대한 서명 검증(HMAC 등)은 이번 릴리스에서 제공하지 않으며, 향후 제공 예정입니다.
등록
POST /reports의callback_url로 리포트별 수신 URL을 지정하거나,- API 클라이언트에 등록된 기본
callback_url을 사용합니다.
이벤트
report.completed
필수 슬롯이 모두 성공해 리포트가 준비되면 전송됩니다. 분석이 끝나면 리포트가 자동으로 공개되고 공유 링크가 생성됩니다.
{
"event": "report.completed",
"report_id": "rpt_01HXEXAMPLE",
"external_inspection_id": "partner-INSP-0001",
"summary_status": "complete",
"share_url": "https://app.atrace.ai/r/sh_abcdef",
"summary": { "min_groove_mm": 5.8, "rank": "A" },
"occurred_at": "2026-06-24T03:02:10Z"
}report.failed
일부 필수 슬롯이 시간 내 완료되지 않으면(timeout-reconcile) 전송됩니다. 이벤트 이름은 report.failed이지만 summary_status 값은 partial이므로, 이벤트 이름(failed)과 값(partial)을 혼동하지 마세요.
{
"event": "report.failed",
"report_id": "rpt_01HXEXAMPLE",
"external_inspection_id": "partner-INSP-0001",
"summary_status": "partial",
"failed_slots": [
{ "module_type": "tire", "slot": { "position": "rear_right", "image_type": "tread" } }
],
"occurred_at": "2026-06-24T03:12:10Z"
}완료 확인은 폴링으로
webhook은 이벤트 알림용이므로, 신뢰 가능한 완료 확인은 GET /reports/{id} 폴링으로 하세요.
status가 published가 되면 리포트가 열람 가능한 상태입니다. summary_status(complete/partial)는 품질 신호일 뿐 준비 여부를 가르는 값이 아니며, share_url은 생성 응답부터 이미 제공되므로 별도의 게이트가 아닙니다.
요청이 429/5xx로 실패하면 지수 백오프로 재시도하세요.