ngrok·Cloudflare Tunnel로 Sume 웹훅 로컬 테스트하기

localhost에서 Sume 웹훅을 테스트하려면 핸들러를 로컬 포트에서 실행하고, ngrok http 8080이나 cloudflared tunnel --url http://localhost:8080으로 노출한 다음, 터널의 HTTPS URL에 핸들러 경로를 붙여 웹훅 URL로 등록하세요. Sume는 localhost, 사설 네트워크, HTTPS가 아닌 웹훅 URL을 거부하므로, 로컬 핸들러에 닿을 수 있게 해 주는 것은 공개 HTTPS 터널입니다.

Sume는 두 도구 어느 쪽에도 전용 커넥터를 제공하지 않습니다. 각 도구는 Sume의 POST를 다른 공개 요청과 똑같이 여러분의 포트로 전달할 뿐입니다. Sume 관련 사실은 웹훅 (영문)과 Run 웹훅 (영문) 문서에서, 터널 동작은 ngrok과 Cloudflare의 자체 문서에서 가져왔으며, 모두 2026-09-27에 확인했습니다. 배포한 엔드포인트가 이벤트를 받지 못한다면 Sume 웹훅이 도착하지 않나요?를 참고하세요.

Sume는 왜 localhost로 웹훅을 보낼 수 없나요?

웹훅 POST는 여러분의 머신이 아니라 Sume에서 오므로, URL은 공개 인터넷에서 접근할 수 있어야 합니다. 문서에 따르면 웹훅 URL은 공개 HTTPS여야 합니다. localhost, 사설 네트워크, HTTPS가 아닌 URL은 제출할 때 400 invalid_request로 거부되고, URL은 전달 시점에 다시 검사됩니다. 현재 코드는 .local, .internal, .test로 끝나는 호스트 이름과, 기본값이 아닌 포트를 명시한 URL도 거부하므로 http://localhost:8080/hooks/sume와 https://my-laptop.local:8443/hooks/sume는 둘 다 실패합니다.

터널은 여러분의 머신으로 전달되는, 기본 포트의 공개 HTTPS 호스트 이름을 제공합니다. 모든 규칙과 정확한 오류는 웹훅 URL이 유효하지 않다고 거부되나요?에 정리되어 있습니다.

ngrok과 Cloudflare Quick Tunnel 중 무엇을 써야 하나요?

둘 다 로컬 포트에 공개 HTTPS URL을 줍니다. ngrok 무료 요금제는 브라우저 경고 페이지를 보여 주지만 HTML 브라우저 트래픽에만 해당하며, ngrok 문서에 따르면 API나 프로그래밍 방식의 요청에는 영향이 없습니다. Cloudflare는 Quick Tunnel이 테스트와 개발 전용이라고 밝힙니다.

로컬 루프는 어떻게 돌리나요?

핸들러를 시작하고, 터널을 열고, 경로까지 포함한 전체 URL을 등록하세요. Sume는 리다이렉트를 따라가지 않으므로, 프레임워크의 트레일링 슬래시 리다이렉트 같은 3xx는 실패한 시도가 됩니다. 터널과 서명 시크릿은 테스트 보내기(Send test)로 확인하세요. 테스트 보내기는 지정한 URL로 서명된 더미 webhook.test 이벤트를 POST하고, 실제 제출과 같은 URL 규칙을 적용하며, 핸들러가 응답한 status_code를 돌려줍니다. 응답 필드는 디버깅 가이드에서 다룹니다.

그다음 터널 URL을 웹훅 URL로 지정해 실제 Job이나 실행을 제출하세요. 기존 Job이 터널을 향하도록 바꿀 수는 없습니다. 다시 보내기(Redeliver)는 다른 URL로 절대 보내지 않으며, Job의 경우 새 URL은 곧 새 Job입니다.

# Terminal 1: your handler listens on localhost:8080. Expose it:
ngrok http 8080
# or, with no account:
cloudflared tunnel --url http://localhost:8080

# Terminal 2: send a signed test event to the printed HTTPS URL plus your path
curl -X POST https://api.sume.com/v1/webhooks/test-deliveries \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "webhook_url": "https://your-assigned-name.ngrok-free.app/hooks/sume" }'

ngrok 인스펙터에서 재생해야 하나요, Sume의 다시 보내기를 써야 하나요?

ngrok의 Traffic Inspector는 각 요청의 헤더와 본문을 보여 주고, Replay는 캡처한 요청을 원본과 같은 메서드, 헤더, 본문으로 다시 보냅니다. Sume 전달이라면 원래의 x-sume-webhook-timestamp와 서명도 그대로 들어갑니다. Sume 문서는 재전송 허용 시간을 벗어난 타임스탬프를 수신기가 거부하도록 안내하며 오 분을 무난한 기본값으로 제시하므로, 인스펙터 재생은 그 시간 안에서만 검증을 통과합니다.

그보다 오래된 이벤트에는 Sume의 다시 보내기(Redeliver)를 쓰세요. jobs:write로 POST /v1/jobs/{job_id}/webhook/redeliver를 호출하거나, formats:write로 POST /v1/format-runs/{run_id}/webhook/redeliver를 호출하면 됩니다. 다시 보내기는 실제 종료 이벤트를 새 타임스탬프와 서명으로 다시 POST하고, 자동 시도를 모두 소진한 뒤에도 동작하며, 10회의 자동 시도 중 하나를 쓰지 않습니다.

로컬 세션에서는 무엇이 깨지나요?

주의할 점은 세 가지입니다.

• Quick Tunnel 재시작: 실행할 때마다 새로운 무작위 trycloudflare.com 서브도메인이 생기고, 웹훅 URL은 Job이나 실행마다 저장되어 전달 시점에 다시 검사됩니다. 재시작 전에 제출한 작업은 여전히 이전 호스트 이름을 향합니다. 반면 ngrok 무료 요금제는 계정에 개발 도메인 하나를 유지합니다.
• 브레이크포인트: 시도마다 10초가 주어지고, 느린 엔드포인트는 이 예산을 다 써 버려 재시도됩니다. Job 전달은 고정 지연(기본 30초)을 두고 최대 10회 시도하며, 실행 전달은 지수적으로 백오프합니다. 이벤트를 저장하고 2xx로 응답한 다음 디버깅하세요.
• 터널 한도: 처리 중인 요청이 200개를 넘으면 Quick Tunnel은 429로 응답하고, Sume는 이를 실패한 시도로 보고 재시도합니다. 실행 전달은 429에 담긴 Retry-After도 존중합니다.