웹훅과 API의 차이는 무엇인가요?

API 호출은 코드가 서버에 무언가를 요청하고 답을 받아 오는 것입니다. 웹훅은 어떤 일이 일어났을 때 서버가 여러분이 알려 준 URL을 호출하는 것입니다. 둘은 양자택일이 아닙니다. 웹훅 자체도 반대 방향으로 보내는 HTTP 요청이며, 두 방식은 함께 동작합니다. API를 호출해 작업을 시작하면, 작업이 끝났을 때 웹훅이나 폴링이 알려 줍니다.

아래 Sume 동작은 실행과 결과 (영문), Job과 결과 (영문), 웹훅 (영문), Run 웹훅 (영문) 문서에서, WebSocket 정의는 MDN의 WebSocket API 페이지에서 가져왔습니다. 모두 2026-09-28에 확인했습니다.

웹훅과 API는 무엇이 다른가요?

차이는 누가 요청을 시작하느냐입니다. API 호출에서는 무언가 필요할 때 코드가 요청을 보냅니다. Job을 만들고, 상태를 읽고, 결과를 가져오는 식입니다. 웹훅에서는 Job이 끝나는 것 같은 이벤트가 일어날 때 제공자가 요청을 보냅니다. 직접 묻는 대신 통보를 받습니다.

오래 걸리는 작업이라면 기다리는 동안 코드가 하는 일이 달라집니다. Sume의 실행 문서는 실행이 끝났음을 알아내는 두 방법을 비교하며, 두 방법은 똑같은 영수증을 전달합니다. 문서가 권하는 프로덕션 방식은 둘 다 쓰는 것입니다. 웹훅은 빠른 경로이고, result_url 읽기는 엔드포인트가 다운된 날을 위한 백업입니다.

웹훅도 API인가요?

어떤 의미에서는 그렇습니다. 웹훅은 제공자가 여러분이 운영하는 엔드포인트로 보내는 HTTP 요청이며, Sume의 경우 JSON 본문을 담은 서명된 POST입니다. 그 엔드포인트는 여러분이 호스팅하고 제공자가 호출하는 작은 API인 셈입니다. 페이로드와 보낼 시점은 제공자가 정하고, URL과 어떤 요청을 유효하게 볼지는 받는 쪽이 정합니다.

방향이 뒤집혀 있기 때문에 웹훅 엔드포인트에는 자체 검사가 필요합니다. 공개 URL에는 누구나 요청을 보낼 수 있으므로, 수신기는 본문을 신뢰하기 전에 서명을 검증합니다. Sume는 전달마다 <timestamp>.<raw_body>에 대한 HMAC-SHA256으로 서명하고, 이를 sume-v1=<hex_signature> 형태로 x-sume-webhook-signature에 담아 보냅니다.

API를 호출하는 대신 언제 웹훅을 써야 하나요?

작업이 요청 하나보다 오래 걸리고 Job마다 루프를 돌리고 싶지 않을 때 웹훅을 쓰세요. 영상 생성이 그런 작업입니다. Sume 문서에 따르면 영상 Job은 제출 요청이 기다릴 수 있는 30초를 넘기는 일이 흔합니다. Sume에서 제출 요청은 첫 응답에 Job ID나 실행 ID를 돌려주며, 2xx는 유료 작업이 진행 중이라는 뜻이지 끝났다는 뜻이 아닙니다. 웹훅 URL을 추가하면 Sume가 그 URL로 종료 이벤트 하나를 POST하며, 그 사이에 진행 이벤트는 없습니다. Format 실행은 실행이 완료되거나 실패할 때, 생성 Job은 Job이 완료되거나 실패하거나 취소될 때 보냅니다.

폴링은 폴백으로 남겨 두세요. 문서는 웹훅을 유일한 복구 경로가 아니라 전달 최적화라고 부르며, 전달이 실패해도 실행이나 Job 자체는 절대 바뀌지 않습니다. 실행에 대한 두 경로는 Sume Format 실행 수명주기에서 다룹니다. 아래 생성 요청은 웹훅을 요청하면서도 폴링 URL을 돌려받습니다.

curl -sS -X POST "https://api.sume.com/v1/formats/acme/product-promo/runs" \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-8823-promo-v1" \
  -d '{
    "input": { "product_url": "https://example.com/p/8823" },
    "communication": { "webhook_url": "https://example.com/hooks/sume" }
  }'

웹훅 엔드포인트에는 무엇이 필요한가요?

누가 웹훅을 보내든 네 가지가 필요합니다. 공개 HTTPS URL, JSON을 파싱하기 전 원본 본문에 대한 서명 검사, 빠른 2xx 응답, 그리고 재시도가 같은 이벤트를 반복하므로 중복 제거입니다. Sume에서는 localhost, 사설 네트워크, HTTPS가 아닌 웹훅 URL이 400 invalid_request로 거부되므로, 내 머신에서는 ngrok·Cloudflare Tunnel로 Sume 웹훅 로컬 테스트하기처럼 터널을 거쳐 테스트하세요. 각 검사는 웹훅 보안 모범 사례에서 하나씩 살펴봅니다.

WebSocket은 어디에 해당하나요?

WebSocket은 세 번째 패턴입니다. 브라우저와 서버 사이의 양방향 세션으로, 클라이언트는 답을 받으려고 폴링하지 않고도 메시지를 보내고 응답을 받을 수 있습니다. 현재 Sume Developer API에는 SSE나 WebSocket 전송이 없으며, GET /v1/jobs/:id/events는 스트림이 아니라 pull 스냅샷입니다. 끝난 Job을 브라우저에 전달하려면 서버에서 웹훅을 받은 뒤, 앱이 이미 페이지와 통신하는 방식으로 넘기세요. 클라이언트가 기다리는 방법은 롱 폴링과 숏 폴링의 차이에서 비교합니다.