개발자
API 연동에 필요한 키 발급, 웹훅 수신, 호출 제어, 플러그인 신청을 다루는 콘솔 화면을 안내합니다.
API 키 관리
Service API 호출에 쓰는 X-API-KEY 값을 발급·조회·폐기합니다. 발급된 키는 조직 단위로 동작하며, 목록에는 누가 만들었는지(작성자)가 함께 남습니다.
캡처 대상: 관리 > 개발자 > API 키 관리
작성자·설명·생성일·상태와 "키 보기" / "폐기" 버튼이 보이게 캡처해주세요.
활성과 폐기됨 상태가 함께 있으면 좋습니다. 키 값은 노출되지 않게 목록 상태로만 캡처해주세요.
웹훅
URL 클릭, 전환 목표 달성, 연락처 변경 같은 이벤트가 생길 때마다 지정한 주소로 HTTP POST를 보냅니다. HTTPS 주소만 등록할 수 있고, 요청에는 위조를 막기 위한 HMAC-SHA256 서명이 함께 실립니다.
웹훅 등록
보낼 수 있는 이벤트
| 분류 | 이벤트 | 발생 시점 | 필요 조건 |
|---|---|---|---|
| 클릭 추적 | URL 클릭 | 단축 URL이 클릭될 때 | - |
| 캠페인 클릭 | 캠페인에 연결된 URL이 클릭될 때 | - | |
| 딥링크 전환 퍼널 | 퍼널 단계 변경 | 클릭 → 스토어 → 설치 → 실행 중 다음 단계로 이동할 때 | 모바일 딥링크 퍼널 애드온 |
| 매출 분석 | 목표 달성 | 회원가입·구매 등 전환 목표가 완료될 때 | 매출 분석 애드온 |
| 사용자 여정 | 세션 이벤트 | 웹/iOS/Android 간 페이지뷰·플랫폼 전환 등이 기록될 때 | 사용자 여정 분석 애드온 |
| 연락처 이벤트 | 연락처 생성 | 새 연락처가 추가될 때 | 메시징 애드온 |
| 연락처 수정 | 연락처 정보가 변경될 때 | ||
| 연락처 삭제 | 연락처가 삭제될 때 | ||
| 수신 거부 | 연락처가 메시지 수신을 거부할 때 | ||
| 메시지 발송 | 메시지 발송 | 메시지가 발송 완료될 때 | 메시징 애드온 |
| 메시지 수신 확인 | 수신자가 메시지를 받았을 때 | ||
| 메시지 발송 실패 | 메시지 발송이 실패했을 때 |
수신 서버 없이 테스트하기
목록 위 "테스트 수신 URL"을 누르면 임시 수신 주소가 발급됩니다. 이 주소를 웹훅의 대상 URL로 설정하면 수신된 헤더와 본문을 콘솔에서 바로 확인할 수 있어, webhook.site 같은 외부 서비스 없이 연동을 검증할 수 있습니다.
전송 결과 확인
목록의 성공/실패 칼럼으로 건강 상태를 한눈에 볼 수 있고, 웹훅을 열면 전송 로그에 시간·이벤트·상태·HTTP 코드·응답시간·에러가 남습니다. 서명 검증 방법과 페이로드 구조는 웹훅 연동 가이드에 있습니다.
캡처 대상: "새 웹훅 추가" 모달
이름·대상 URL 입력칸과 이벤트 유형 선택 목록(클릭 추적·퍼널·매출·연락처·메시지 발송)이 보이게 캡처해주세요.
아래 고급 설정(재시도 횟수·타임아웃)까지 들어가면 좋습니다.
IP 화이트리스트
Service API(X-API-KEY 인증) 호출을 등록된 IP에서만 받도록 제한합니다. 등록되지 않은 IP의 요청은 모두 차단됩니다.
- 단일 IP만 지원합니다. 192.168.1.100, 203.0.113.45 형식으로 입력합니다. 대역(CIDR) 표기는 지원하지 않습니다.
- 여러 IP가 필요하면 각각 개별 등록합니다.
- 설명란에 용도(예: "운영 배치 서버")를 적어두면 나중에 어떤 항목을 지워도 되는지 판단하기 쉽습니다.
캡처 대상: 웹훅 상세의 "전송 로그" 영역
시간·이벤트·상태·HTTP·응답시간·에러 칼럼이 보이게 캡처해주세요.
성공 건과 실패 건이 섞여 있으면 상태 확인 방법을 설명하기 좋습니다.
API 호출 한도
Service API(/api/v1/service/**) 호출은 조직별로 분당 요청 수가 제한됩니다. 이 화면에서는 현재 한도와 남은 여유를 확인만 할 수 있고, 값 변경은 관리자만 가능합니다.
동작 방식
- 요청 1회당 토큰 1개가 소비되고, 토큰은 설정된 주기마다 자동으로 보충됩니다.
- 한도를 넘기면 429 Too Many Requests가 반환됩니다.
- 시스템 기본값은 1분당 30회이며, 조직별로 다른 값이 설정되어 있으면 화면에 "커스텀"으로 표시됩니다.
응답 헤더
| 헤더 | 설명 | 예시 |
|---|---|---|
| X-RateLimit-Limit | 최대 요청 가능 횟수 | 30 |
| X-RateLimit-Remaining | 현재 남은 요청 가능 횟수 | 25 |
| Retry-After | 한도 초과 시 재시도까지 대기 시간(초) | 30 |
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 30
X-RateLimit-Retry-After-Seconds: 30
{
"error": "TOO_MANY_REQUESTS",
"message": "Service API 호출 한도를 초과했습니다. 30초 후에 다시 시도해주세요.",
"retryAfterSeconds": 30
}
캡처 대상: 관리 > 개발자 > API 호출 한도
"현재 API 호출 한도" 카드(요청 수 / 주기)와 설정 정보(조직명·요청 수 제한·제한 주기·시스템 기본값)가 보이게 캡처해주세요.
아래 응답 헤더 안내 표까지 담기면 좋습니다.
단축 URL 플러그인
파트너 사이트에 스크립트 태그 한 줄을 붙여 단축 URL 생성·통계 위젯을 노출하는 기능입니다. 이 화면에서는 사용 신청과 키·허용 도메인 관리를 합니다.
운영 중 잠시 멈추려면 카드 우측 상단의 "중지"를, 다시 켜려면 "재시작"을 누릅니다. 관리자가 중지시킨 경우에는 스스로 재시작할 수 없고 고객지원 문의가 필요합니다.
캡처 대상: 관리 > 개발자 > 단축 URL 플러그인
신청이 완료된 카드의 CLIENT ID · 설치 코드 · 허용 도메인 영역이 보이게 캡처해주세요.
CLIENT ID는 일부 마스킹해주세요.