플랫폼 콜백

Kollus Live는 라이브 송출 시작/종료, 녹화 파일 전송 등 주요 이벤트 발생 시 고객사가 사전에 지정한 URL로 알림(콜백, Callback)을 전송합니다. 이를 통해 외부 시스템과의 실시간 동기화 및 작업 자동화를 구현할 수 있습니다.

플랫폼 콜백 종류

• 라이브 콜백: 라이브 송출 상태 확인
• 녹화 파일 전송 콜백: 생성된 녹화 파일의 전송 결과 확인

콜백 설정 방법

콜백 URL은 채널별로 독립적으로 설정할 수 있습니다.

1. Kollus Live 콘솔 > [채널 관리] > [채널 리스트]로 이동합니다.
2. 상황에 따라 다음 중 하나를 선택합니다.
   • 신규 채널 생성 시 설정: 우측 상단의 [채널 등록]을 클릭합니다.
   • 기존 채널에 설정: 대상 채널 우측 [수정]을 클릭합니다.
3. 화면 하단의 [콜백] 탭에서 목적에 맞는 콜백 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) 정보는 인증 및 API 키 문서를 참고하세요.

라이브 콜백

라이브 송출 상태가 변경될 때 전송되는 정보입니다.

파라미터	타입	설명
version	string	콜백 버전
service_account_key	string	서비스 계정 키
channel_key	string	채널 키
stream_key	string	스트림 키
broadcast_key	string	라이브 방송 키
broadcast_state	string	라이브 송출 상태 start: 스트림 시작 stop: 스트림 종료 pause: 송출 단절 시 방송 유지 시간에 따른 스트림 정지 resume: 송출 단절 시 방송 유지 시간에 따른 스트림 재시작

녹화 파일 전송 콜백

녹화 파일 전송 기능 사용 시, 파일 전송 결과 정보를 포함합니다.

파라미터	타입	설명
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	녹화 방식 segment: 자동 녹화 duplicate: 수동 녹화
recording_file_transfer_result	integer	파일 전송 결과 0: 실패 1: 성공