플랫폼 콜백
Kollus VOD는 업로드, 트랜스코딩, 콘텐츠 관리 등 주요 워크플로우가 완료될 때, 고객사가 지정한 URL로 알림(콜백, Callback)을 전송합 니다. 이를 통해 외부 시스템과의 실시간 동기화 및 작업 자동화를 구현할 수 있습니다.
플랫폼 콜백 종류
- 업로드 콜백
- 트랜스코딩 콜백
- 콘텐츠 업데이트 콜백
- 콘텐츠 채널 추가 콜백
- 콘텐츠 채널 삭제 콜백
콜백 설정 방법
콜백 URL은 Kollus VOD 콘솔에서 설정할 수 있습니다. 상세한 설정 위치는 콜백 설정 - 플랫폼 콜백 문서를 참고하세요.
콜백 흐름
통신 규격
전송 방식
- Method:
POST - Content-Type:
application/x-www-form-urlencoded - 전송 시점: 이벤트 발생 즉시 전송
응답 조건
고객사 서버는 요청을 수신한 후 아래 조건을 준수하여 응답해야 합니다.
- 성공 응답: HTTP Status Code 200 반환 (응답 본문은 무시됨)
- 실패 판정: 200 이외의 상태 코드 반환 또는 Timeout 발생 (재시도 큐에 등록됨)
Timeout 제한
| 구분 | 제한 시간 | 설명 |
|---|---|---|
| Connect Timeout | 2초 | 서버 연결 시도 제한 시간 |
| Response Timeout | 3초 | 요청 전송 후 응답 대기 제한 시간 |
재시도
재시도 정책
일시적인 네트워크 장애나 고객사 서버 지연으로 전송 실패 시, 시스템은 자동으로 재시도를 수행합니다.
- 재시도 간격: 5분 간격
- 최대 횟수: 3회 (최초 전송 포함 총 4회 시도)
- 로그 확인: 모든 전송 및 재시도 결과는 로그에 기록됩니다.
⚠️ 콜백 중복 수신 방지
네트워크 지연으로 인해 고객사 서버가 정상 처리 후 응답을 보냈음에도 불구하고, Kollus 시스템에서 Timeout으로 인지하여 콜백을 재전송할 수 있습니다.
- 권장 사항: 고객사 시스템은 동일한 이벤트를 중복 수신하더라도 데이터 정합성에 문제가 없도록 중복 처리 방지 로직을 반드시 적용해야 합니다.
요청 파라미터
각 이벤트별로 전송되는 파라미터 명세입니다.
ℹ️참고
식별 키 정보는 서비스 연동 키 문서를 참고하세요.
업로드 완료 콜백
| 파라미터 | 타입 | 설명 |
|---|---|---|
content_provider_key | string | 서비스 계정 키 |
full_filename | string | 폴더 경로 포함 원본 파일 이름 |
filename | string | 원본 파일 이름 |
upload_file_key | string | 업로드 파일 키 |
트랜스코딩 완료 콜백
| 파라미터 | 타입 | 설명 |
|---|---|---|
content_provider_key | string | 서비스 계정 키 |
filename | string | 원본 파일 이름 |
upload_file_key | string | 업로드 파일 키 |
transcoding_result | string | 트랜스코딩 결과
|
콘텐츠 업데이트 완료 콜백
| 파라미터 | 타입 | 설명 |
|---|---|---|
content_provider_key | string | 서비스 계정 키 |
full_filename | string | 폴더 경로 포함 원본 파일 이름 |
filename | string | 원본 파일 이름 |
upload_file_key | string | 업로드 파일 키 |
update_type | string | 업데이트 유형 (content_*) |
콘텐츠 채널 추가 완료 콜백
| 파라미터 | 타입 | 설명 |
|---|---|---|
content_provider_key | string | 서비스 계정 키 |
full_filename | string | 폴더 경로 포함 원본 파일 이름 |
filename | string | 원본 파일 이름 |
upload_file_key | string | 업로드 파일 키 |
media_content_key | string | 미디어 콘텐츠 키 |
channel_key | string | 콘텐츠가 등록된 채널 식별 키 |
channel_name | string | 콘텐츠가 등록된 채널 이름 |
profile_key | string | 적용된 인코딩 프로파일 키 리스트 (| 구분자 사용) |
update_type | string | 업데이트 유형 (channel_join) |
콘텐츠 채널 삭제 완료 콜백
| 파라미터 | 타입 | 설명 |
|---|---|---|
content_provider_key | string | 서비스 계정 키 |
full_filename | string | 폴더 경로 포함 원본 파일 이름 |
filename | string | 원본 파일 이름 |
upload_file_key | string | 업로드 파일 키 |
media_content_key | string | 미디어 콘텐츠 키 |
channel_key | string | 콘텐츠가 등록된 채널 식별 키 |
channel_name | string | 콘텐츠가 등록된 채널 이름 |
update_type | string | 업데이트 유형 (channel_leave) |