Kollus VOD는 업로드, 트랜스코딩, 콘텐츠 관리 등 주요 워크플로우가 완료 될 때, 고객사가 사전에 지정한 URL로 알림(콜백, Callback)을 전송합니다.
이를 통해 외부 시스템과의 연동이나 자동화를 손쉽게 구현할 수 있습니다.
플랫폼 콜백의 종류는 다음과 같습니다.
- 업로드 콜백
- 트랜스코딩 콜백
- 콘텐츠 업데이트 콜백
- 콘텐츠 채널 추가 콜백
- 콘텐츠 채널 삭제 콜백
콜백 설정 방법
콜백 URL은 Kollus VOD 콘솔에서 설정할 수 있습니다.
상세한 설정 위치는 콜백 설정 - 플랫폼 콜백 문서를 참고하세요.
콜백 흐름
통신 규격
전송 방식
- HTTP Method:
POST
- Content-Type:
application/x-www-form-urlencoded
- 전송 시점: 이벤트 발생 즉시 발송을 원칙으로 합니다.
응답 조건
- 성공 조건: 고객사 서버는 HTTP Status Code 200으로 응답해야 합니다.(응답 본문은 처리 로직에 영향을 주지 않고 무시됩니다.)
- 실패 조건: 200 이외의 상태 코드를 반환하거나 Timeout이 발생 시 전송 실패로 간주하고 재시도 큐에 등록됩니다.
Timeout 제한
- Connect Timeout: 2초
- Response Timeout: 3초
재시도
재시도 규칙
- 전송 실패 시 5분 간격으로 최대 3회까지 재시도합니다.
- 재시도 이력은 로그로 기록됩니다.
⚠️ 콜백 중복 수신 방지
- 발생 상황: 네트워크 지연으로 인해 고객사 서버는 정상 처리 후 200 응답을 보냈으나, Kollus 측에서 Response Timeout으로 인지하여 콜백을 재전송할 수 있습니다.
- 중복 처리 방지 로직 적용: 고객사 시스템은 동일한 이벤트를 중복 수신하더라도 데이터 정합성에 문제가 없도록 중복 처리 방지(Idempotency) 로직을 반드시 적용해야 합니다.
요청 파라미터
업로드 완료 콜백
| 파라미터 | 타입 | 설명 |
|---|
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) |