웹훅
콜백 형식, HMAC 서명, 재생 방지, 재전송.
createTask에 callBackUrl을 지정하면 작업이 종료 상태가 될 때 알림이 큐에 추가됩니다. queued에서 running으로 바뀌는 중간 알림은 없습니다. v2 재전송은 같은 request_id와 업무 데이터를 유지하고 url 및 expiresAt만 갱신합니다. 실제 수신 본문으로 서명을 검증하고 request_id로 중복을 제거하세요.
signature = base64(
HMAC-SHA256(
secret,
"<task_id>.<timestamp>.<sha256_hex(raw_body)>"
)
)서명 검증
X-Webhook-Signature는 HMAC-SHA256의 Base64 값입니다. 서명 대상 문자열은 <task_id>.<timestamp>.<sha256_hex(raw_body)>이고 task_id는 data.taskId에서 읽습니다. JSON을 다시 직렬화하지 말고 수신한 raw body를 그대로 해시하세요.
X-Webhook-Timestamp가 허용 범위를 벗어나면 서명이 유효해도 거부하세요. 서명은 상수 시간 비교 함수로 검증하고 계정에 비어 있지 않은 webhook secret을 설정합니다.
중복 전송 처리
request_id는 전송 ID이며 재전송에서도 바뀌지 않습니다. 데이터베이스에 고유 제약을 두고 이미 처리했다면 2xx를 반환하세요. 먼저 수락해 내부 큐에 넣고 무거운 작업은 응답 후 실행합니다.
failed 작업도 body.code는 200입니다. 성공 여부는 반드시 data.state로 판단합니다.
전체 필드 정의는 OpenAPI 3.1 사양을 확인하세요.