플랫폼 콜백
Kollus Live는 라이브 송출 시작/종료, 녹화 파일 전송 등 주요 이벤트 발생 시 고객사가 사전에 지정한 URL로 알림(콜백, Callback)을 전송합니다. 이를 통해 외부 시스템과의 실시간 동기화 및 작업 자동화를 구현할 수 있습니다.
플랫폼 콜백 종류
- 라이브 콜백: 라이브 송출 상태 확인
- 녹화 파일 전송 콜백: 생성된 녹화 파일의 전송 결과 확인
콜백 설정 방법
콜백 URL은 채널별로 독립적으로 설정할 수 있습니다.
- Kollus Live 콘솔 > [채널 관리] > [채널 리스트]로 이동합니다.
- 상황에 따라 다음 중 하나를 선택합니다.
- 신규 채널 생성 시 설정: 우측 상단의 [채널 등록]을 클릭합니다.
- 기존 채널에 설정: 대상 채널 우측 [수정]을 클릭합니다.
- 하단의 [콜백] 탭에서 목적에 맞는 콜백 URL을 입력한 후 [저장]을 클릭합니다.
콜백 흐름
통신 규격
전송 방식
- 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으로 인지하여 콜백을 재전송할 수 있습니다.
- 권장 사항: 고객사 시스템은 동일한 이벤트를 중복 수신하더라도 데이터 정합성에 문제가 없도록 중복 처리 방지 로직을 반드시 적용해야 합니다.
요청 파라미터
각 이벤트별로 전송되는 파라미터 명세입니다.
관련 정보
키(Key/ID) 정보는 아래 문서를 참고하세요.
라이브 콜백
라이브 송출 상태가 변경될 때 전송되는 정보입니다.
| 파라미터 | 타입 | 설명 |
|---|---|---|
version | string | 콜백 버전 |
service_account_key | string | 서비스 계정 키 |
channel_key | string | 채널 키 |
stream_key | string | 스트림 키 |
broadcast_key | string | 라이브 방송 키 |
broadcast_state | string | 라이브 송출 상태
|
녹화 파일 전송 콜백
녹화 파일 전송 기능 사용 시, 파일 전송 결과 정보를 포함합니다.
| 파라미터 | 타입 | 설명 |
|---|---|---|
version | string | 콜백 버전 |
service_account_key | string | 서비스 계정 키 |
channel_key | string | 채널 키 |
stream_key | string | 스트림 키 |
broadcast_key | string | 라이브 방송 키 |
recording_file_id | integer | 녹화 파일 고유 식별자 |
recording_file_filename | string | 녹화 파일 이름 |
recording_file_kind | string | 녹화 방식
|
recording_file_transfer_result | integer | 파일 전송 결과
|