웹훅 활용법: 영상이 완성되면 바로 알림 받기

영상 생성에는 시간이 걸립니다. 5~10초 영상은 보통 몇 분에서 15분 정도, 30초 영상은 20~30분이 걸리며, 사용량이 몰리는 시간대에는 대기열이 생기기도 합니다. 지금까지는 몇 초마다 작업 상태를 조회해야 했습니다. 루프를 짜고, 타임아웃을 처리하고, 서비스가 재시작되면 아직 끝나지 않은 작업이 무엇인지도 기억해 두어야 했습니다.

이제는 그럴 필요가 없습니다. 작업이 끝나는 순간, 성공이든 실패든 결과를 서버로 바로 보내 드립니다.

받는 방법은 두 가지

• 계정 기본 주소: 콘솔에서 ‘설정 → 웹훅’을 열고, 이벤트를 받을 URL을 입력한 뒤 원하는 이벤트를 선택합니다. 이후 API로 제출한 영상·이미지 작업은 끝날 때마다 결과가 이 주소로 전송됩니다.
• 요청별 지정: 작업을 제출할 때 callback_url을 넣으면 그 작업의 결과는 이 URL로만 전송됩니다. callBackUrl로 쓰는 것이 익숙하다면 그대로 써도 됩니다.

curl https://nezhagate.com/v1/videos/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "seedance-2.5", "prompt": "비 오는 밤거리를 떠내려가는 종이배", "duration": 5,
       "callback_url": "https://your-app.com/webhooks/nezhagate"}'

활용 사례

• 영상 앱, 미니 프로그램, 웹사이트: 사용자는 제출하자마자 페이지를 닫아도 됩니다. 영상이 준비되면 알림을 받으니, 그때 사용자에게 앱 내 메시지나 문자, 이메일을 보내고 완성된 영상을 사용자의 보관함에 넣으면 됩니다.
• 이미지 대량 생성: 상품 사진이나 광고 이미지 수백 장을 한 번에 제출하면, 한 장씩 완성되는 대로 미디어 라이브러리나 CDN에 저장됩니다. 실패한 건은 따로 기록되므로 프롬프트를 다듬어 다시 제출하면 됩니다.
• 챗봇: 누군가 Telegram, Discord, Lark, WeCom 그룹에 프롬프트를 올리면 봇이 바로 "생성 중…"이라고 답하고, 알림이 오면 영상을 그룹에 올립니다.
• 서버리스 함수: Vercel, Cloudflare Workers, 클라우드 함수는 30분 동안 도는 폴링 루프에 맞지 않습니다. 함수는 제출 직후 바로 끝내도 되고, 다음 단계는 알림이 도착하면 시작됩니다.
• 잔액 부족 알림: 잔액이 설정한 크레딧 수 아래로 내려가면 알림을 한 번 받습니다. 팀의 Slack, Lark, DingTalk 채널로 보내 두면, 한밤중에 서비스가 멈춘 뒤가 아니라 잔액이 바닥나기 전에 누군가 충전할 수 있습니다.

믿고 써도 되는 이유

• 검증 가능: 모든 알림에는 Standard Webhooks 방식의 서명이 붙습니다(OpenAI 웹훅도 같은 방식을 씁니다). 대부분의 언어에 바로 쓸 수 있는 라이브러리가 있어, 코드 몇 줄이면 알림이 정말 저희가 보낸 것인지 확인할 수 있습니다.
• 자동 재시도: 서버가 10초 안에 2xx로 응답하지 않으면 1분, 5분, 30분, 2시간, 6시간 후에 다시 보냅니다. 재시도해도 이벤트 ID가 그대로이므로 중복을 쉽게 걸러낼 수 있습니다.
• 빠짐없는 내용: 알림에는 작업 조회 엔드포인트가 반환하는 내용이 그대로 담기며, 영상 URL과 사용량도 포함됩니다. 실패한 작업은 이미 전액 환불되었고, 알림에 실패 이유가 적혀 있습니다.
• 기록 보관: 콘솔에서 최근 전송 내역과 각각의 결과를 볼 수 있습니다. 내역은 30일간 보관되며, 원하는 건을 다시 보낼 수도 있습니다.

3단계로 설정하기

1. 서버에 POST 요청을 받는 URL을 준비합니다. 웹훅 문서에 Python과 Node.js로 서명을 검증하는 전체 예제가 있습니다.
2. 콘솔에서 ‘설정 → 웹훅’을 열고 URL을 입력한 뒤, ‘테스트 이벤트 보내기’를 눌러 알림이 도착하는지 확인합니다.
3. 평소처럼 작업을 제출하고 알림을 기다리면 됩니다. 특정 작업의 결과만 다른 곳으로 받으려면 그 요청에 callback_url을 추가합니다.