웹훅 기초: LotShow API가 사진 완성을 알려 주는 방법

스튜디오 사진은 완성되기까지 조금 시간이 걸려요. 시스템이 몇 초마다 LotShow에 다 됐는지 물어볼 수도 있고, LotShow가 완성되는 순간 시스템에 알려 줄 수도 있어요. 두 번째 방식이 웹훅이고, LotShow API는 이 방식으로 결과를 전달해요.

폴링 vs 웹훅

폴링은 상태가 바뀔 때까지 코드가 타이머로 GET /v1/jobs/{id}를 호출하는 방식이에요. 작동은 하지만 대부분의 호출은 새 소식 없이 돌아오고, 처리하는 차가 많을수록 호출도 늘어나요.

웹훅은 이걸 뒤집어요. 작업을 만들 때 LotShow에 URL을 알려 주면, 작업이 끝났을 때 LotShow가 그 URL로 결과를 담은 HTTPS POST를 보내요. 할 일이 생기기 전까지 시스템은 아무것도 하지 않아도 돼요.

이벤트

• job.completed: 스튜디오 사진이 완성됐어요. 완성된 이미지의 URL이 함께 와요.
• job.failed: 사진을 완성하지 못했고, 크레딧은 환불됐어요.
• credits.low: 공유 잔액이 20크레딧 아래로 떨어졌어요.

엔드포인트마다 받을 이벤트를 고를 수 있어서, 재고 시스템은 완성된 사진만 받고 결제 도구는 잔액 부족 알림만 받게 할 수 있어요.

전달되는 내용

완성된 작업은 작은 JSON 본문으로 도착해요.

{
  "event": "job.completed",
  "created_at": "2026-10-14T09:41:40.000Z",
  "id": "Hn4kR2pXq8VbT1sLw0Za",
  "backdrop": "white-hall",
  "vehicle_id": "pQ7mT2vK9cLx4RbN1sHd",
  "name": "stock-4471",
  "output_url": "https://firebasestorage.googleapis.com/v0/b/…/default.jpg?alt=media&token=…",
  "seconds": 62,
  "credits_left": 319
}

id는 작업을 만들 때 돌려받은 작업 id예요. 그래서 작업 id를 시스템의 재고 번호 옆에 저장해 두면 좋아요. 웹훅은 어떤 작업이 끝났는지 알려 주고, 기록은 그게 어떤 차인지 알려 줘요.

좋은 엔드포인트 만들기

1. 빠르게 응답하세요. 이벤트가 도착하면 바로 2xx 상태로 응답하고, 이미지 다운로드 같은 실제 작업은 백그라운드에서 하세요.
2. 중복을 예상하세요. LotShow는 엔드포인트가 응답할 때까지 다시 보내기 때문에, 타임아웃 뒤 등에 같은 전달이 두 번 이상 올 수 있어요. 다시 처리하기 전에 이미 처리한 이벤트인지 확인하세요.
3. 순서를 가정하지 마세요. 1초 간격으로 보낸 두 작업도 어느 쪽이든 먼저 끝날 수 있어요. 도착 시간이 아니라 작업 id로 결과를 맞추세요.
4. 서명을 확인하세요. 모든 전달은 설정에 있는 계정의 서명 시크릿으로 서명되고, 서명은 webhook-id, webhook-timestamp, webhook-signature 헤더에 담겨 와요(Standard Webhooks 방식). 검증되지 않는 것은 모두 거부하세요.
5. 모두 기록하세요. 모든 전달의 원본 본문과 시간을 남겨 두세요. 뭔가 이상해 보일 때 가장 먼저 보게 될 곳이 로그예요.

운영 전에 테스트하기

설정의 각 엔드포인트에는 테스트 보내기 버튼이 있고, API에는 POST /v1/webhooks/{id}/test가 있어요. 둘 다 엔드포인트로 샘플 이벤트를 보내서, 크레딧을 쓰지 않고 핸들러를 확인할 수 있어요. 엔드포인트가 정확히 무엇을 받는지 보려면 요청 검사 도구나 로컬 터널을 쓰면 편해요.

개발을 시작해 볼까요? API 키는 프로와 엘리트 요금제에 포함돼요. 설정의 API 키에서 만들 수 있어요.