엔드포인트 상세
개요
엔드포인트 상세는 하나의 엔드포인트와 관련된 모든 설정을 다루는 페이지입니다. 이 화면 하나로 다음이 가능해요.
- 엔드포인트 정보 확인·수정 (이름·설명·URL·버전)
- 활성 / 비활성 전환
- 프로덕션 배포 및 재배포
- 기본 API 키 관리
- 필수 필드 추가·삭제
- 웹훅 · 시스템 알림 설정
- 엔드포인트 삭제
협업키 관리(키 발급·초대·권한 설정)는 별도 페이지에서 진행합니다. 자세한 내용은 협업키 관리 문서를 참고하세요.
협업자로 참여하고 있는 경우, 본인이 권한을 가진 일부 섹션만 보입니다(소유자 전용 섹션은 자동 숨김).
진입 경로
- 상단 메뉴 APIs → 목록에서 원하는 엔드포인트 이름 클릭
- 대시보드 최근 활동 에서 해당 엔드포인트 클릭
- 온보딩 1단계 완료 후 자동 이동
Free 플랜 경고 배너
Free 플랜을 사용 중인 경우 상단에 노출됩니다. Free 플랜에서는 엔드포인트를 마음껏 만들어 보고, 다양한 설정을 자유롭게 시험해 볼 수 있어요. 생성 후 7일이 지나면 자동으로 정리되지만, 언제든 다시 만들 수 있으니 부담 없이 사용해 보세요.
활성/비활성 및 배포 버튼
소유자 전용 영역입니다.
- 활성/비활성 버튼 (Power 아이콘): 모든 환경에서 잠시 API 호출을 멈추고 싶을 때 사용합니다. 비활성 중에는 호출이 거부되지만, 데이터는 그대로 보존됩니다.
프로덕션에 배포버튼 (Sandbox 탭에서만):- 샌드박스의 현재 설정을 프로덕션에 복제해 배포합니다
- 조건: 샌드박스에서 최소 1회 이상 테스트 호출을 성공한 뒤여야 활성화됩니다
협업자가 접속한 경우 위 두 버튼 대신 배포 요청 버튼이 보입니다. 소유자에게 배포 요청 메시지를 보낼 수 있어요.
환경 탭
상단 바 바로 아래에 Sandbox | Production 두 탭이 있어요. 두 환경은 완전히 독립적으로 설정됩니다.
기본 운영 사이클은 다음과 같습니다: 샌드박스에서 테스트하고 협업자와 충분히 협의 → 프로덕션에 배포 → 운영. 변경이 필요하면 다시 샌드박스에서 수정 후 재배포하는 흐름을 권장합니다.
Sandbox
- 샌드박스 API 키(
tm_test_)로 호출되는 환경 - 테스트 전용. 실제 운영 전 자유롭게 실험하세요
- 샌드박스 데이터는 30일 뒤 자동 삭제됩니다 (모든 플랜 공통)
Production
- 프로덕션 API 키(
tm_live_)로 호출되는 환경 - 실제 운영용. 계정이 유효한 동안 데이터는 영구 보존되며, 30일 이상 경과한 레코드는 자동으로 아카이브됩니다 (유료 플랜)
- 프로덕션 배포 전에는 프로덕션 API 키 호출이 거부되며 로그에도 남지 않습니다
개요 카드
엔드포인트의 기본 정보를 담는 섹션입니다.
| 항목 | 설명 |
|---|---|
| 설명 | 엔드포인트 설명. Sandbox 탭에서 소유자가 인라인 편집 가능 |
| 엔드포인트 URL | 실제 API 호출 주소. 이 URL로 POST/GET/PUT/DELETE 요청을 보냅니다. 복사 버튼 제공 |
| 버전 | 설정 버전. 배포할 때마다 증가 |
| 생성일 | 엔드포인트 생성 시각 |
| 수정일 | 마지막 설정 변경 시각 (Sandbox) |
| 배포일 | 프로덕션 배포 시각 (Production 탭에서만 표시) |
기본 API 키
소유자 전용 영역입니다.
- 엔드포인트 생성 시 함께 발급된 기본 API 키입니다
- 오른쪽의 테스트하기 버튼으로 이동하는 테스트 및 연동 가이드 페이지에서 이 키로 인증이 이루어집니다
- 표시 / 숨김 토글로 키를 화면에서 가리거나 노출할 수 있어요
- 재발급 버튼: 이전 키가 즉시 무효화됩니다. 노출이 의심될 때만 사용하세요
협업자가 접속하면 이 섹션 대신 본인에게 할당된 협업키 카드가 표시됩니다.
협업 키
여기서는 요약 카드만 제공되고, 키 추가·초대·권한 관리는 별도의 관리 페이지에서 진행합니다.
- 소유자 뷰:
전체 보기버튼과 협업자별 요약 (이름 · 초대 수락 수) - 협업자 뷰: 본인에게 발급된 키의 권한 배지 목록
자세한 사용법은 협업키 관리 문서를 참고하세요.
필수 필드
API 호출 시 반드시 포함되어야 하는 JSON 필드를 정의합니다. 자세한 설명은 새 엔드포인트 생성 가이드를 참고하세요.
- 필드를 추가하거나 수정하려면
수정버튼을 누르세요 - 편집 중에는 필드 추가·삭제·타입 변경이 가능하며,
저장또는취소로 마무리합니다 - 저장하면 Sandbox 설정이 업데이트되며, 프로덕션에 반영하려면 다시 배포해야 합니다
- 배포 후 필수 필드를 수정해도 기존에 저장된 데이터는 변경되지 않습니다. 수정된 필드 규칙은 이후 새로 들어오는 호출에만 적용됩니다
웹훅
소유자 전용 영역입니다.
엔드포인트에 API 호출이 성공적으로 처리되면, 지정한 웹훅 URL로 2차 요청을 보낼 수 있어요. 데이터 저장은 웹훅 성공 여부와 무관하게 항상 완료됩니다.
입력 항목
- 웹훅 URL: 웹훅을 받을 주소 (HTTPS 권장)
- 인증 헤더 (선택): 인증 헤더 키. 기본값
Authorization - 인증 값 (선택): 인증 헤더 값. 예:
Bearer abc123
인증이 필요 없는 웹훅(단순 수신 서버, URL 자체에 토큰 포함 등)은 인증 필드를 비워둬도 됩니다.
웹훅 정책 요약
- 재시도: 실패 시 최대 3회, 1s → 2s 백오프로 재시도
- 타임아웃: 7초 이내 응답 필요. 초과 시 실패 처리
웹훅 페이로드
API 호출이 처리되면 아래와 같은 JSON 페이로드가 웹훅 URL로 전송됩니다. 스크린샷 하단의 웹훅 페이로드 예시 영역을 펼치면 실제 형식을 확인할 수 있어요.
| 필드 | 설명 |
|---|---|
| id | 저장된 레코드의 고유 ID |
| operation | 수행된 작업 (create, update, delete) |
| status | 처리 결과 (success, failed) |
| endpoint_slug | 엔드포인트 식별자 |
| payload | 협업자(API 호출자)가 전송한 원본 JSON 데이터 그대로 포함 (delete 시 null) |
| target_record_id | 대상 레코드 ID (update/delete 시 포함) |
| processed_at | 처리 완료 시각 |
협업자 웹훅
협업자도 웹훅이 필요한 경우, API 호출 시 요청 헤더에 X-Webhook-Callback 등을 포함하여 자체 웹훅을 설정할 수 있습니다. 협업자 웹훅은 소유자 웹훅과 별도로 독립 동작하며, 페이로드 형식은 소유자 웹훅과 동일합니다. 자세한 설정 방법은 테스트 및 연동 가이드를 참고하세요.
알림
웹훅과는 별개로, 시스템 이벤트만 Discord · Slack · Telegram으로 알리는 기능입니다. 요청 페이로드는 전송되지 않고, 어떤 이벤트가 발생했는지만 알려줍니다.
구조
- 환경 탭 분리 없음: 알림 설정은 환경별로 나뉘지 않고, 엔드포인트 단위로 관리됩니다
- 소유자 뷰: 단일 알림 설정 카드
- 협업자 뷰: 본인에게 할당된 협업키별로 알림 카드가 표시됩니다
입력 항목
- 채널 선택: Discord / Slack / Telegram
- 웹훅 URL: 각 플랫폼에서 미리 발급받은 봇/웹훅 주소
- 채팅 ID: Telegram의 경우에만 필요
각 플랫폼의 웹훅/봇 설정 방법은 해당 플랫폼 공식 문서를 참고하세요.
알림 항목
| 이벤트 | 수신자 | 설명 |
|---|---|---|
| 웹훅 전달 실패 (본인 웹훅만) | 해당 당사자만 | 소유자 웹훅 실패 → 소유자 / 협업자 웹훅 실패 → 협업자 |
| 월간 사용량 80% 경고 (소유자만) | 소유자 | 월 사용량 80% 도달 시 |
| 월간 사용량 한도 초과 (소유자만) | 소유자 | 월 사용량 100% 초과 시 |
| 새 배포 요청 (소유자만) | 소유자 | 협업자가 프로덕션 배포를 요청한 시점 |
| 배포 완료 (협업자만) | 협업자 | 소유자가 배포를 완료한 시점 |
주의
- 알림 전송이 실패해도 재시도하지 않으며, 전송 이력은 저장되지 않습니다
- 알림 메시지는 모두 영문입니다
위험 영역
소유자 전용 영역입니다.
엔드포인트 삭제버튼- 삭제하면 다음이 즉시, 영구적으로 제거됩니다:
- 엔드포인트 설정 자체
- 샌드박스 · 프로덕션의 모든 API 레코드
- 관련 통계 / 배포 요청 / 웹훅 / 알림 설정 / 협업키 / 아카이브 메타데이터
- 협업자에게도 접근이 차단됩니다
- 복구 불가이므로 확인 다이얼로그에서 이름을 입력해야 진행됩니다
오른쪽 사이드바
상세 페이지 오른쪽에는 환경에 따라 다른 퀵 카드가 표시됩니다.
API 호출 기록
이 엔드포인트로 들어온 API 호출의 결과를 확인할 수 있는 페이지로 이동합니다. 요청 성공/실패, 페이로드, 웹훅 상태 등을 상세하게 조회할 수 있어요.
샌드박스 테스트
Sandbox 탭에서 표시됩니다.
별도의 도구 없이 브라우저에서 직접 API 호출을 테스트하고, 연동 방법을 확인할 수 있는 페이지로 이동합니다. 자세한 사용법은 테스트 및 연동 가이드를 참고하세요.
프로덕션 콘솔
Production 탭에서, 배포 완료 후 소유자에게만 표시됩니다.
프로덕션 데이터를 대시보드에서 직접 관리할 수 있는 콘솔입니다. 예를 들어, 고객사가 GET으로 조회할 상품 목록이나 공지사항 같은 데이터를 미리 등록해두고 싶을 때 유용해요. POST(생성), GET(조회), PUT(수정), DELETE(삭제) 모두 지원합니다. 콘솔은 소유자의 API 키로 실행되며, 협업자 웹훅은 발동하지 않습니다. 소유자 웹훅이 설정되어 있다면 정상적으로 호출됩니다. 자세한 사용법은 프로덕션 콘솔 가이드를 참고하세요.
배포 요청 알림
Sandbox 탭에서 표시됩니다.
협업자가 프로덕션 배포를 요청하면 여기에 표시됩니다. 이 알림은 이메일로도 함께 발송되므로 놓칠 걱정은 없어요. 전체 보기 버튼을 누르면 모든 배포 요청 이력을 확인할 수 있습니다.
자주 막히는 부분
- 배포 버튼이 비활성이에요: 샌드박스에서 테스트 호출이 한 번도 없는 상태거나, 이미 샌드박스 최신 버전이 프로덕션에 반영된 상태예요. 샌드박스에서 테스트를 한 번 실행한 뒤 확인하세요
- Production 탭에 기록이 없어요: 배포 전까지 프로덕션 호출은 거부되어 기록이 남지 않습니다. 배포가 성공했는지,
tm_live_키를 쓰고 있는지 확인하세요 - 필수 필드를 고쳤는데 운영에 반영이 안 돼요: Sandbox 수정은 자동으로 프로덕션에 반영되지 않습니다.
프로덕션에 배포를 다시 눌러주세요 - 웹훅이 안 도착해요: 웹훅 서버가 7초 안에 응답하지 않으면 실패로 처리됩니다. 서버가 공개 인터넷에서 접근 가능한지, HTTPS를 사용하고 있는지 확인하세요. 또한 Discord나 Slack 같은 플랫폼은 자체적으로 호출 횟수 제한(Rate Limit)이 있어서, 짧은 시간에 너무 많은 웹훅이 발생하면 일부가 차단될 수 있습니다. 수신 측 플랫폼의 전송 제한 정책도 함께 확인해 보세요