엔드포인트 상세

개요

엔드포인트 상세는 하나의 엔드포인트와 관련된 모든 설정을 다루는 페이지입니다. 이 화면 하나로 다음이 가능해요.

• 엔드포인트 정보 확인·수정 (이름·설명·URL·버전)
• 활성 / 비활성 전환
• 프로덕션 배포 및 재배포
• 기본 API 키 관리
• 필수 필드 추가·삭제
• 웹훅 설정
• 엔드포인트 삭제

협업키 관리(키 발급·초대·권한 설정)는 별도 페이지에서 진행합니다. 자세한 내용은 협업키 관리 문서를 참고하세요.

협업자로 참여하고 있는 경우, 본인이 권한을 가진 일부 섹션만 보입니다(소유자 전용 섹션은 자동 숨김).

진입 경로

• 상단 메뉴 APIs → 목록에서 원하는 엔드포인트 이름 클릭
• 대시보드 최근 활동 에서 해당 엔드포인트 클릭
• 온보딩 1단계 완료 후 자동 이동

---

Free 플랜 경고 배너

Free 플랜을 사용 중인 경우 상단에 노출됩니다. Free 플랜에서는 엔드포인트를 마음껏 만들어 보고, 다양한 설정을 자유롭게 시험해 볼 수 있어요. 생성 후 7일이 지나면 자동으로 정리되지만, 언제든 다시 만들 수 있으니 부담 없이 사용해 보세요.

활성/비활성 및 배포 버튼

소유자 전용 영역입니다.

• 활성/비활성 버튼 (Power 아이콘): 모든 환경에서 잠시 API 호출을 멈추고 싶을 때 사용합니다. 비활성 중에는 호출이 거부되지만, 데이터는 그대로 보존됩니다.
• 프로덕션에 배포 버튼 (Sandbox 탭에서만):
  • 샌드박스의 현재 설정을 프로덕션에 복제해 배포합니다
  • 조건: 샌드박스에서 최소 1회 이상 테스트 호출을 성공한 뒤여야 활성화됩니다

협업자가 접속한 경우 위 두 버튼 대신 배포 요청 버튼이 보입니다. 소유자에게 배포 요청 메시지를 보낼 수 있어요.

환경 탭

상단 바 바로 아래에 Sandbox | Production 두 탭이 있어요. 두 환경은 완전히 독립적으로 설정됩니다.

기본 운영 사이클은 다음과 같습니다: 샌드박스에서 테스트하고 협업자와 충분히 협의 → 프로덕션에 배포 → 운영. 변경이 필요하면 다시 샌드박스에서 수정 후 재배포하는 흐름을 권장합니다.

Sandbox

• 샌드박스 API 키(tm_test_)로 호출되는 환경
• 테스트 전용. 실제 운영 전 자유롭게 실험하세요
• 샌드박스 데이터는 30일 뒤 자동 삭제됩니다 (모든 플랜 공통)

Production

• 프로덕션 API 키(tm_live_)로 호출되는 환경
• 실제 운영용. 레코드는 최소 60일 보관되며, 이후 월 단위로 한꺼번에 삭제됩니다. 남겨야 할 데이터는 웹훅이나 목록 API로 들어오는 즉시 내보내 주세요
• 프로덕션 배포 전에는 프로덕션 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 자체에 토큰 포함 등)은 인증 필드를 비워둬도 됩니다.

웹훅 정책 요약

• 타임아웃: 15초 이내 응답 필요. 초과 시 실패 처리
• 응답 코드: 2xx는 "성공했다"가 아니라 "받았다"는 뜻입니다. 여러분 쪽 처리가 실패해도 2xx를 반환하고, 그 실패는 여러분 시스템에 기록하세요. 5xx는 배달 자체가 도달하지 않았다는 신호라 같은 레코드를 아래 재시도 일정대로 다시 보내며, 여러분 수신기는 그때마다 같은 작업을 다시 실행하게 됩니다
• 재시도: 프로덕션은 총 6회 시도 — 최초 배달 1회 + 재시도 5회(30초·2분·10분·1시간·4시간, 약 5시간). 샌드박스는 총 4회 시도 — 최초 배달 1회 + 재시도 3회(30초·2분·10분, 약 12분)
• 재시도함: 5xx, 429, 타임아웃, 연결 오류. 429에 Retry-After가 붙어 있으면 그만큼 더 기다립니다 (기본 간격보다 짧게 당기지는 않습니다)
• 재시도하지 않음: 429를 제외한 모든 4xx. 409도 포함됩니다. 설정을 고치면 다음 호출부터 정상 전달됩니다
• 실패 확인: 실패했거나 재시도 중인 배달은 로그 화면의 웹훅 배달에 남습니다. 정상 전달된 웹훅은 기록되지 않아요
• 이메일 알림: 배달을 포기하면 메일로 알려드립니다 (재시도 소진, 또는 재시도하지 않는 영구 응답). 플랜과 무관하게(무료 포함) 받으실 수 있고 프로덕션 웹훅만 해당하며, 엔드포인트당 하루 한 통까지이고 복구 알림은 없어요. 협업자 웹훅 실패는 메일로 알리지 않습니다 — 그 URL은 소유자가 바꿀 수 없으니까요
• 멱등성: 모든 시도가 같은 X-3minapi-Record-Id를 실어 보냅니다. 중복 판단에 쓰세요
• 서명: 모든 요청에 HMAC-SHA256 서명(webhook-signature)을 붙입니다. 자세한 내용은 아래 웹훅 서명 시크릿을 참고하세요

웹훅 서명 시크릿

웹훅 설정 카드 바로 아래에 있습니다. 소유자 전용이 아니라 협업자도 볼 수 있는 영역이에요 — 협업자가 X-Webhook-Callback으로 직접 받는 웹훅도 같은 시크릿으로 서명되기 때문입니다.

• 환경별로 다릅니다 — 샌드박스 탭과 프로덕션 탭의 시크릿이 각각 별개입니다. 받는 환경의 값을 쓰세요
• 조회는 소유자·협업자 모두 가능합니다
• 재발급(회전)은 소유자만 할 수 있습니다. 협업자 화면에는 재발급 버튼이 나타나지 않아요
• 정기적으로 돌릴 값이 아닙니다. 재발급은 시크릿이 유출됐을 때의 대응 수단입니다
• 재발급하면 24시간 동안 새 서명과 이전 서명이 함께 전송됩니다. 그 사이 아무 때나 수신 서버의 값을 교체하면 배달이 끊기지 않아요. 유예 기간에는 카드에 만료 시각 배너가 표시됩니다

이 값으로 무엇을 어떻게 하는지는 웹훅 서명 검증에서 확인하세요.

웹훅 페이로드

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 등을 포함하여 자체 웹훅을 설정할 수 있습니다. 협업자 웹훅은 소유자 웹훅과 별도로 독립 동작하며, 페이로드 형식은 소유자 웹훅과 동일합니다. 자세한 설정 방법은 테스트 및 연동 가이드를 참고하세요.

협업자 웹훅도 소유자 웹훅과 같은 재시도 정책·같은 서명이 적용됩니다. 서명 검증에 쓸 시크릿은 위의 웹훅 서명 시크릿 카드에서 확인할 수 있어요.

위험 영역

소유자 전용 영역입니다.

• 엔드포인트 삭제 버튼
• 삭제하면 다음이 즉시, 영구적으로 제거됩니다:
  • 엔드포인트 설정 자체
  • 샌드박스 · 프로덕션의 모든 API 레코드
  • 관련 통계 / 배포 요청 / 웹훅 / 협업키
• 협업자에게도 접근이 차단됩니다
• 복구 불가이므로 확인 다이얼로그에서 이름을 입력해야 진행됩니다

오른쪽 사이드바

상세 페이지 오른쪽에는 환경에 따라 다른 퀵 카드가 표시됩니다.

API 호출 기록

이 엔드포인트로 들어온 API 호출의 결과를 확인할 수 있는 페이지로 이동합니다. 요청 성공/실패, 페이로드, 웹훅 상태 등을 상세하게 조회할 수 있어요.

샌드박스 테스트

Sandbox 탭에서 표시됩니다.

별도의 도구 없이 브라우저에서 직접 API 호출을 테스트하고, 연동 방법을 확인할 수 있는 페이지로 이동합니다. 자세한 사용법은 테스트 및 연동 가이드를 참고하세요.

프로덕션 콘솔

Production 탭에서, 배포 완료 후 소유자에게만 표시됩니다.

프로덕션 데이터를 대시보드에서 직접 관리할 수 있는 콘솔입니다. 예를 들어, 고객사가 GET으로 조회할 상품 목록이나 공지사항 같은 데이터를 미리 등록해두고 싶을 때 유용해요. POST(생성), GET(조회), PUT(수정), DELETE(삭제) 모두 지원합니다. 콘솔은 소유자의 API 키로 실행되며, 협업자 웹훅은 발동하지 않습니다. 소유자 웹훅이 설정되어 있다면 정상적으로 호출됩니다. 자세한 사용법은 프로덕션 콘솔 가이드를 참고하세요.

배포 요청 알림

Sandbox 탭에서 표시됩니다.

협업자가 프로덕션 배포를 요청하면 여기에 표시됩니다. 이 알림은 이메일로도 함께 발송되므로 놓칠 걱정은 없어요. 전체 보기 버튼을 누르면 모든 배포 요청 이력을 확인할 수 있습니다.

---

자주 막히는 부분

• 배포 버튼이 비활성이에요: 샌드박스에서 테스트 호출이 한 번도 없는 상태거나, 이미 샌드박스 최신 버전이 프로덕션에 반영된 상태예요. 샌드박스에서 테스트를 한 번 실행한 뒤 확인하세요
• Production 탭에 기록이 없어요: 배포 전까지 프로덕션 호출은 거부되어 기록이 남지 않습니다. 배포가 성공했는지, tm_live_ 키를 쓰고 있는지 확인하세요
• 필수 필드를 고쳤는데 운영에 반영이 안 돼요: Sandbox 수정은 자동으로 프로덕션에 반영되지 않습니다. 프로덕션에 배포를 다시 눌러주세요
• 웹훅이 안 도착해요: 웹훅 서버가 15초 안에 응답하지 않으면 실패로 처리됩니다. 서버가 공개 인터넷에서 접근 가능한지, HTTPS를 사용하고 있는지 확인하세요. 또한 Discord나 Slack 같은 플랫폼은 자체적으로 호출 횟수 제한(Rate Limit)이 있어서, 짧은 시간에 너무 많은 웹훅이 발생하면 일부가 차단될 수 있습니다. 수신 측 플랫폼의 전송 제한 정책도 함께 확인해 보세요