콘텐츠로 이동

웹훅

웹훅 URL이 구성되면, 파일 번역 작업(/jobs)이 완료될 때(성공 여부와 관계없이) 서버로 알림이 전송됩니다. POST /jobs/{id}/cancel로 취소된 작업은 콜백을 보내지 않습니다. 문서 작업 및 미디어 작업의 경우, 각각의 쿼리 엔드포인트를 통해 상태를 조회하십시오.

API를 통해 관리되며, 사용자당 최대 3개까지 가능합니다:

POST /api/v1/webhooks create
GET /api/v1/webhooks list
PATCH /api/v1/webhooks/{id} update / disable
DELETE /api/v1/webhooks/{id} delete

예제 생성:

Terminal window
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-url
Content-Type: application/json
X-Webhook-Event: job.completed
X-Webhook-Timestamp: 1782900150
X-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 hashlib
import hmac
import json
import 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는 각 웹훅의 마지막 트리거 시간, 상태 코드 및 연속 실패 횟수를 표시합니다.