GloopAPI 연동 가이드
Webhook 수신
서명 검증, 재전송과 알림 설정입니다.
현재 Webhook 알림은 일반 동영상 작업이 정산되고 종료 상태에 도달한 후에 적용됩니다. 동기 이미지, 음성 또는 영구 보관 작업 공간에도 같은 구독 기능이 있다고 가정하지 마세요. 알림에는 프롬프트, 결과 URL이나 원본 서비스 오류가 포함되지 않습니다.
설정과 구독
계정 Webhook에서 HTTPS 수신 엔드포인트를 만들고 한 번만 표시되는 서명 비밀키를 저장하세요. 관리 작업은 공개 Bearer API가 아닌 로그인 세션을 사용하며 비밀키는 API 키와 다릅니다. 동영상 요청에는 같은 계정에 활성화된 webhook_endpoint_id를 전달해야 하며 임의의 콜백 URL은 허용되지 않습니다. 이 필드는 멱등 입력의 일부이므로 재전송 시 엔드포인트를 바꿀 수 없습니다.
서명 검증과 중복 제거
{"id":"evt_example","type":"video.succeeded","created_at":1790000000,"data":{"task_id":"vid_example","status":"succeeded"}}
이벤트 유형은 video.succeeded, video.failed 또는 video.cancelled입니다. 원본 요청 바이트를 보존하고 Webhook-Id, Webhook-Timestamp와 Webhook-Signature를 검증하세요. 서명은 v1=<hex>입니다. HMAC-SHA256의 키는 비밀키 문자열이며 메시지는 이벤트 ID, 초 단위 Unix 타임스탬프와 원본 본문을 두 개의 줄바꿈으로 연결하되 마지막 줄바꿈은 포함하지 않습니다.
import hashlib, hmac
message = event_id.encode() + b"\n" + timestamp.encode() + b"\n" + raw_body
expected = hmac.new(secret.encode(), message, hashlib.sha256).hexdigest()
valid = hmac.compare_digest(received_hex, expected)
요청 크기를 제한하고 누락되거나 중복된 헤더와 알 수 없는 서명 버전을 거부하며 시계 오차를 검사하세요(최대 5분 권장). 서명 검증이 성공한 뒤에만 JSON을 파싱하고 본문의 id가 Webhook-Id와 같은지 확인하세요. 예제는 서명 계산과 비교만 수행하므로 수신 측에서 위의 검증도 구현해야 합니다.
2xx를 반환하기 전에 이벤트를 안정적으로 영구 저장하거나 멱등 처리를 완료하세요. 안정적인 이벤트 ID로 중복을 제거합니다. 재시도는 본문과 ID를 유지하며 타임스탬프와 서명을 갱신합니다. 이벤트를 받으면 원래 API 키로 작업/결과를 조회하세요. 알림 자체는 결과 다운로드 자격 증명이 아닙니다.
재시도와 교체
네트워크 오류, 408, 429와 5xx는 자동 대기 후 재시도를 유발합니다. 2xx만 성공입니다. 리디렉션은 따르지 않으며 그 밖의 4xx는 자동 재시도하지 않습니다. 전달은 최대 12회, 최대 24시간 동안 시도합니다. 이후에는 계정에서 확인하고 명시적으로 재전송하세요. 재전송은 알림만 다시 전달하며 콘텐츠를 다시 생성하거나 생성 요금을 추가로 발생시키지 않습니다.
엔드포인트를 갱신하거나 비밀키를 교체하면 버전이 증가하고 이전 대기 전달이 중지됩니다. 명시적인 재전송만 현재 주소와 비밀키를 사용합니다. 비활성화하면 새 시도를 막지만 이미 보낸 요청을 회수하지는 못하므로 비밀키 교체 시 수신 측도 갱신하세요. 상태와 정산의 관계는 비동기 작업과 멱등성을 참고하세요.