웹훅
웹훅 URL이 구성되면, 파일 번역 작업(/jobs)이 완료될 때(성공 여부와 관계없이) 서버로 알림이 전송됩니다. POST /jobs/{id}/cancel로 취소된 작업은 콜백을 보내지 않습니다. 문서 작업 및 미디어 작업의 경우, 각각의 쿼리 엔드포인트를 통해 상태를 조회하십시오.
웹훅 관리
섹션 제목: “웹훅 관리”API를 통해 관리되며, 사용자당 최대 3개까지 가능합니다:
POST /api/v1/webhooks createGET /api/v1/webhooks listPATCH /api/v1/webhooks/{id} update / disableDELETE /api/v1/webhooks/{id} delete예제 생성:
curl -X POST https://omnidoc.top/api/v1/webhooks \ -H "X-API-Key: sk_your_key" \ -H "Content-Type: application/json" \ -d '{ "url": "https://your-server.com/hooks/omnidoc", "secret": "your-signing-secret", "events": ["job.completed"], "description": "Production callback" }'URL은 공용 인터넷에서 접근 가능해야 하며, 가급적 HTTPS을 통해 연결되어야 합니다. 사설 네트워크, 로컬 주소 및 잘못된 형식의 URL은 400을 반환합니다. PATCH 요청은 url, secret, events, description 및 status를 변경할 수 있습니다(active / disabled).
콜백 형식
섹션 제목: “콜백 형식”POST your-webhook-urlContent-Type: application/jsonX-Webhook-Event: job.completedX-Webhook-Timestamp: 1782900150X-Webhook-Signature: sha256=...{ "event": "job.completed", "timestamp": 1782900150, "data": { "job_id": "q3f8s6c2a9m1k4tx", "status": "completed", "file_name": "report.docx", "char_count": 12840 }}이벤트
섹션 제목: “이벤트”| 이벤트 | 언제 |
|---|---|
job.completed | 작업이 종료됩니다; data.status은 completed 또는 failed입니다. |
실패한 작업에도 job.completed 이벤트가 사용되며, data.status == "failed" 및 선택적 data.error을 통해 구분할 수 있습니다. 성공한 작업에는 error 필드가 없습니다. data.char_count는 번역 문자 수를 나타내며, 실패한 작업의 경우 0이 적용됩니다.
events은 job.completed 및 *(모든 이벤트)만 허용하며, 다른 값이나 빈 목록을 입력하면 422를 반환합니다. PATCH 요청에서는 변경하지 않을 필드를 생략하십시오; null을 전송해도 422가 반환됩니다.
서명을 검증합니다.
섹션 제목: “서명을 검증합니다.”웹훅에 secret을 설정하면 모든 콜백에는 X-Webhook-Signature이 포함됩니다. 원시 요청 본문에서 HMAC-SHA256로 이를 확인하십시오:
import hashlibimport hmacimport jsonimport time
def verify_webhook(payload: bytes, signature: str, secret: str) -> bool: expected = hmac.new( secret.encode(), payload, hashlib.sha256 ).hexdigest() return hmac.compare_digest(f"sha256={expected}", signature)
def parse_webhook(payload: bytes, signature: str, secret: str, tolerance: int = 12 * 3600) -> dict: if not verify_webhook(payload, signature, secret): raise ValueError("invalid signature") event = json.loads(payload) if abs(time.time() - event["timestamp"]) > tolerance: raise ValueError("stale event") return event서명은 헤더가 아닌 본문만을 포함합니다. 재전송 보호를 위해, 서명 검증 통과 후 본문에서 timestamp을 확인하고(X-Webhook-Timestamp과 동일하지만 서명 대상은 본문 값에 한정됨), data.job_id 및 data.status로 중복 제거를 수행합니다. 재전송 시 첫 번째 배달의 본문을 그대로 유지하며 동일한 timestamp을 사용하고, 마지막 재전송은 첫 번째 배달 이후 약 8.6시간 뒤에 이루어지므로 해당 시간보다 창을 더 짧게 설정하지 마십시오(예시에서는 12시간을 사용함).
- 수신자는 배달이 성공적으로 처리되려면 15초 이내에
2xx을 반환해야 하며, 리디렉션은 처리되지 않습니다. - 전송 실패(시간 초과, 연결 오류 또는
2xx외) 시 자동 재전송: 이전 실패 발생 후 1분, 5분, 30분, 2시간, 6시간 간격으로 최대 이벤트당 6회 전송 후 더 이상 재전송하지 않음 - 재시도는 본문이 변경되지 않은 채 웹훅의 현재 URL로 전송되며(
timestamp,data및 서명은 첫 번째 배달과 일치합니다. 중간에secret이 변경된 경우, 새로운secret으로 서명됩니다); 이미 전달된 이벤트는 다시 전송되지 않습니다. - 웹훅이 비활성화되거나 삭제되거나 해당 이벤트에 대한 구독이 해지되면, 보류 중인 재시도가 취소됩니다.
- 수신자는
data.job_id및data.status에 따라 이벤트를 멱등적으로 처리하고, 이를 안전하게 지속한 후 신속히 응답해야 합니다. - 한 계정의 여러 웹훅은 병렬로 전달되며, 처리 속도가 느린 수신자는 다른 웹훅의 처리를 지연시키지 않습니다.
- 10회 연속 실패한 배달(재시도 포함) 후 웹훅은 자동으로 비활성화되며, 수신자가 복구되면
PATCH를 사용하여 다시 활성화하십시오. GET /api/v1/webhooks는 각 웹훅의 마지막 트리거 시간, 상태 코드 및 연속 실패 횟수를 표시합니다.