app_installation.created를 받고, 계정이 앱을 제거하면 app_installation.deleted를 받습니다. 각 설치에는 앱만 변경할 수 있는 두 가지 값도 저장됩니다. external_id는 설치를 자체 시스템의 레코드에 연결하고, metadata는 동기화 커서 같은 작은 값을 보관합니다.
Whop을 통해 결제를 받는 스토어프론트
이 가이드는 가상의 앱을 예로 듭니다. Market Lane은 온라인 스토어 빌더이며, Market Lane의 Whop 앱을 사용하면 비즈니스가 Market Lane 스토어에서 Whop을 통해 결제를 받을 수 있습니다. 모든 스토어에는river-coffee 같은 핸들이 있으며, Market Lane의 모든 체크아웃은 이 핸들로 시작합니다.
Market Lane은 세 가지를 알아야 합니다:
- 비즈니스가 앱을 설치하는 시점. 그래야 비즈니스의 스토어를 연결할 수 있습니다.
- 스토어에서 체크아웃이 시작될 때 어떤 Whop 계정이 결제를 받는지.
- 비즈니스가 앱을 제거하는 시점. 그래야 해당 스토어가 체크아웃에서 Whop 제공을 중단할 수 있습니다.
1
앱에 필요한 권한 요청하기
앱의 권한에서 계정에 체크아웃을 생성하기 위한
checkout_configuration:create와, 결제 완료 시점을 알기 위한 webhook_receive:payments를 요청하세요. 비즈니스는 앱을 설치할 때 두 권한을 모두 승인합니다.2
앱의 웹훅 구독하기
계정이 아닌 앱에 속하는 웹훅 하나를 생성하세요. 키에는 앱을 소유한 계정에 대한
resource_id를 앱의 ID로 설정합니다. 이 웹훅은 앱을 설치하는 모든 계정의 설치 이벤트와, 해당 계정들이 허용한 결제 이벤트를 받습니다.developer:manage_webhook 권한이 필요합니다. 응답의 webhook_secret을 저장하고, 웹훅에 설명된 대로 모든 전송을 검증하세요.설치 이벤트는 앱 자체의 웹훅만 받습니다. 계정의 웹훅은 해당 계정에 설치된 앱의 이벤트라도 절대 받지 않습니다.3
비즈니스가 앱을 설치하면 스토어 연결하기
app_installation.created는 data에 설치 정보를 담고 있습니다. 엔벨로프의 account_id는 앱을 설치한 비즈니스입니다:river-coffee를 선택하면 Market Lane은 해당 핸들을 설치의 external_id로 저장합니다:4
체크아웃이 시작되면 계정 찾기
쇼핑객이 결과에는 최대 하나의 설치가 포함되며, 그
river-coffee에서 결제를 진행합니다. 요청에는 스토어 핸들만 포함되므로 Market Lane은 external_id로 설치를 조회합니다:account.id가 결제를 받는 계정입니다. Market Lane은 POST /checkout_configurations로 해당 계정에 체크아웃을 생성하고, 자체 주문 ID를 metadata에 넣은 다음, 쇼핑객을 purchase_url로 보냅니다. 설치 자체가 매핑 역할을 하므로 Market Lane은 스토어 핸들과 Whop 계정의 테이블을 따로 보관하지 않습니다.5
주문을 결제 완료로 표시하기
payment.succeeded가 같은 웹훅으로 도착합니다. 그 account_id는 스토어의 비즈니스이며, 결제에는 체크아웃의 metadata가 포함되어 있으므로 Market Lane은 ID로 주문을 찾아 결제 완료로 표시합니다.6
비즈니스가 앱을 제거하면 Whop 결제 끄기
비즈니스가 앱을 제거하는 즉시
app_installation.deleted가 도착합니다. Market Lane은 river-coffee의 체크아웃에서 Whop 제공을 바로 중단하므로, 쇼핑객이 실패할 체크아웃에 도달하지 않습니다. 설치는 더 이상 GET /app_installations에 나타나지 않으며, 앱은 더 이상 해당 계정에서 작업할 수 없습니다.7
재설치 시 다시 연결하기
비즈니스가 앱을 다시 설치하면 또 다른
app_installation.created를 받습니다. 이는 같은 설치입니다. id, created_at, external_id, metadata가 모두 그대로 돌아옵니다. Market Lane은 페이로드에서 external_id: "river-coffee"를 확인하고, 비즈니스에 다시 연결을 요청하지 않고 해당 스토어의 Whop 결제를 다시 켭니다.설치에 자체 ID 저장하기
external_id는 앱의 설치 전체에서 고유합니다. 다른 설치가 이미 가진 값을 설정하면409가 반환되므로, 두 비즈니스가 같은 스토어를 차지할 수 없습니다. 값은 대소문자를 구분합니다.River-Coffee와river-coffee는 다릅니다.metadata는 병합됩니다. 전송한 키는 설정되고,null로 설정한 키는 제거되며, 생략한 키는 변경되지 않고,{}는 모든 키를 지웁니다. 값은 문자열입니다.- 제거된 설치는
external_id를 유지합니다. 비즈니스가 앱을 제거한 상태인 동안에는 앱의 다른 설치가 그 값을 사용할 수 없습니다. 비즈니스가 앱을 다시 설치하면 값도 함께 돌아옵니다. - 비밀 정보를 저장하지 마세요. 개발자 계정은
metadata와external_id를 읽을 수 있습니다.
반복 이벤트 처리하기
- 반복을 예상하세요. 비즈니스는 앱을 설치, 제거한 뒤 다시 설치할 수 있습니다. 이미 알고 있는 설치에 대한
app_installation.created는 재설치로 처리하세요. webhook-id로 중복을 무시하세요. Whop은2xx응답을 받지 못한 전송을 재시도하며, 재시도 시 같은webhook-id가 유지됩니다.
설치를 읽을 수 있는 주체
다음 단계
웹훅
서명을 검증하고, 재시도를 처리하고, 모든 이벤트를 확인하세요.
App Installations API 레퍼런스
앱 설치의 모든 필드와 엔드포인트.
결제 받기
체크아웃을 생성하고
payment.succeeded로 주문을 처리하세요.권한
앱이 설치 시 요청하는 권한을 선언하세요.

