웹훅 URL이 유효하지 않다고 거부되나요? Sume 웹훅 URL 규칙

Sume는 공개 HTTPS URL이 아닌 웹훅 URL을 400 invalid_request로 거부합니다. 일반 http://, localhost, 사설 네트워크 주소, URL 안의 자격 증명은 모든 Job과 실행에서 거부되며, 현재 코드는 :8443 같은 기본값이 아닌 포트도 거부합니다. 검사는 무엇이든 만들어지기 전에 이루어지므로, URL을 고쳐서 다시 제출하면 됩니다.

문서화된 규칙은 Run 웹훅 (영문), 실행과 결과 (영문), 웹훅 (영문)에서 가져왔으며, 모두 2026-09-27에 확인했습니다. 현재 코드로 표시한 규칙은 API 소스에서 읽은 것이며, 문서에는 나오지 않습니다. URL이 수락된 뒤 전달이 실패하거나 도착하지 않는 경우는 Sume 웹훅이 도착하지 않나요?에서 다룹니다.

Sume는 어떤 웹훅 URL을 거부하나요?

현재 코드에서는 하나의 검사가 생성 Job의 webhook_url과 그 별칭 callback_url(POST /v1/videos의 callback_url 포함), Format·Action·Agent Completion 실행의 communication.webhook_url, 그리고 테스트 보내기(Send test)를 모두 담당합니다. IP 주소로 쓴 호스트라면 현재 코드는 169.254.169.254 같은 링크 로컬 주소, 캐리어급 NAT, 멀티캐스트, 그리고 IPv6 루프백·고유 로컬·링크 로컬 범위도 거부합니다.

400 응답은 어떻게 생겼나요?

거부는 모두 400 invalid_request이지만, 현재 코드에서는 표면에 따라 문구가 다릅니다. 실행 생성과 테스트 보내기는 메시지와 details.field에 필드 이름을 담습니다. 생성 Job 제출은 Invalid request body.로 응답하고 이유를 details.errors[]에 넣습니다. 필드를 가리키는 path, 그리고 어느 필드를 썼든 똑같은 webhook_url must be a valid public HTTPS URL 메시지입니다. 둘 다 retryable: false, next_action: fix_input인 validation 오류이므로 같은 URL을 다시 보내면 똑같이 실패합니다. 다음은 실행 생성 오류를 문서에 나오는 필드만 남겨 줄인 것입니다.

{
  "error": {
    "code": "invalid_request",
    "message": "webhook_url must be a public HTTPS URL without credentials or an explicit port.",
    "request_id": "req_…",
    "details": { "field": "webhook_url" }
  }
}

브라우저에서는 열리는 URL이 왜 거부되나요?

브라우저에서 접근할 수 있다고 해서 허용되는 것은 아닙니다. 확인할 이유는 다음과 같습니다.

• 포트가 있습니다. https://staging.example.com:8443/hooks는 브라우저에서 열릴 수 있지만, 현재 코드는 기본값 443이 아닌 포트를 모두 거부하고 443 포트로 전달합니다. 핸들러를 기본 HTTPS 포트에서 제공하세요.
• api.default.svc.cluster.local이나 host.docker.internal 같은 내부 이름입니다. 현재 코드는 .local, .internal, .test, .localhost로 끝나는 이름을 거부합니다.
• 일반 HTTP를 쓰거나 URL에 사용자 이름과 비밀번호를 넣었습니다. Sume는 HMAC-SHA256으로 전달에 서명하므로 대신 서명을 검증하세요. 방법은 Sume 영상 실행용 서명된 웹훅에 있습니다.
• 여러분 자신의 머신입니다. POST는 Sume에서 오므로, 로컬 작업에서는 Sume 웹훅 로컬 테스트처럼 핸들러 앞에 공개 HTTPS 터널을 두세요.
• 본문이 스스로 모순됩니다. webhook_url과 callback_url의 값이 다르거나, Job 제출에서 URL 없이 mode: "webhook"을 보낸 경우입니다. 둘 다 역시 400 invalid_request입니다.

Sume가 전달할 때 URL을 다시 검사하나요?

네. 문서에 따르면 URL은 전달 시점에 공개 HTTPS URL인지 다시 검증되며, 리다이렉트는 따라가지 않습니다. 3xx는 실패한 시도이므로 최종 URL을 등록하세요. 현재 코드는 전달할 때 호스트 이름도 해석하며, 해석된 주소 중 하나라도 공개 주소가 아니면 전달을 거부하고, 검사한 주소로만 연결합니다.

그래서 공개 주소처럼 보이지만 내부 주소로 해석되는 이름은 제출은 통과해도 전달에서 실패합니다. Job이나 실행은 실제 결과를 그대로 유지하고, webhook_delivery에는 failed와 함께 이유가 last_error에 나타나며, 현재 코드는 차단된 대상을 재시도하지 않습니다. 아예 해석되지 않는 이름은 일시적 실패로 보고 재시도합니다. 다시 보내기(Redeliver)는 다른 URL로 절대 보내지 않으므로, 고친 URL로 받으려면 새 Job이나 실행이 필요합니다.

실제 작업을 제출하기 전에 URL은 어떻게 확인하나요?

테스트 보내기(Send test)를 쓰세요. /dashboard/webhooks의 컨트롤을 쓰거나 account:write로 POST /v1/webhooks/test-deliveries를 호출하면 되며, Job이나 실행은 절대 만들지 않습니다. 같은 URL 규칙을 적용하므로 같은 URL에는 400 invalid_request로 응답합니다. 현재 코드에서는 전달 시점의 DNS 검사도 실행합니다. 공개되지 않은 주소로 해석되는 이름은 status_code: null과 함께, 이유를 error에 담아 돌아옵니다. 응답의 나머지 부분은 Sume 웹훅이 도착하지 않나요?에서 다룹니다.