Skip to main content
웹훅은 이벤트가 발생할 때 Whop이 서버로 보내는 POST 요청입니다. 이벤트의 예: 결제 성공, 멤버십 활성화, 분쟁 시작. 공개 URL을 등록하면, 구독한 이벤트가 발생할 때마다 Whop이 이 URL로 서명된 JSON 이벤트를 보냅니다.
Whop 웹훅은 Standard Webhooks 사양을 사용합니다. Whop SDK는 한 번의 호출로 서명을 검증하고 이벤트를 파싱합니다. Go의 경우 이 페이지 하단의 SDK 없이 검증을 사용하세요.

웹훅의 형태

각 이벤트는 하나의 POST 요청입니다:
엔벨로프는 data와 마찬가지로 웹훅의 api_version_date 고정 버전을 따릅니다. 2026-08-14 이전으로 고정된 웹훅과 고정 버전이 없는 웹훅은 계정 필드를 account_id 대신 company_id로 받습니다. HTTP 요청 헤더도 같은 방식으로 버전이 관리됩니다: 향후 헤더 변경은 날짜가 지정된 API 버전으로 출시되며, 고정 버전은 통합할 때 사용한 헤더를 유지합니다. 네 개의 헤더는 계약상 고정되어 있으며 어떤 버전에서도 변경되지 않습니다: webhook-id, webhook-signature, webhook-timestamp, content-type — 서명 검증은 모든 고정 버전에서 동일하게 작동합니다. 선택적 엔벨로프 필드 하나가 변경된 내용을 설명합니다:
  • previous_attributes — 변경 사항을 캡처하는 .updated 이벤트(account.updated, product.updated, plan.updated, shipment.updated)에 존재합니다: 변경된 data 필드의 이전 값을 필드 이름을 키로 하여 담은 객체입니다. 계정 이름을 “Shine Time Auto Detailing”으로 변경하면 {"title": "Webb's Mobile Detailing"}이 전달됩니다 — 쓰기 전에 각 변경된 필드가 가지고 있던 값입니다. 이 필드가 없으면 해당 이벤트에 대한 변경 캡처를 사용할 수 없었던 것입니다. 값은 data와 마찬가지로 웹훅의 api_version_date 고정 버전을 따릅니다.

구독 결제 복구

은행이 구매자에게 세션 외부 청구를 확인하도록 요청하면 Whop은 payment.requires_action을 발생시킵니다. 구매자가 Whop에 로그인하여 해당 결제의 3D Secure를 완료할 수 있도록 data.recovery_url을 구매자에게 보내세요. 세션 내 체크아웃에서는 구매자가 이미 인증을 진행 중이므로 이 이벤트가 발생하지 않습니다. 구독 갱신이 실패하면 payment.failed도 발생합니다. 가능한 경우 data.decline_code와 data.failure_message에서 이유를 확인하고, data.recovery_url이 있으면 여기서도 사용하세요. Payment 리소스를 조회할 때도 동일한 recovery_url 필드를 사용할 수 있습니다. 결제 목록에는 복구 링크가 포함되지 않습니다. 인증 복구를 사용할 수 없거나 member:basic:read 권한이 없으면 null입니다. 링크를 열어도 청구가 시작되지 않습니다: 구매자가 확인해야 하며, Whop은 결제를 여전히 복구할 수 있는지 확인합니다. 복구 후에는 결과에 대해 payment.succeeded 또는 payment.failed를 계속 처리하세요.

웹훅 생성

응답에는 webhook_secret이 포함됩니다. API는 이 값을 단 한 번만 표시합니다. 즉시 저장하세요. resource_id(웹훅을 소유한 계정 또는 앱)와 child_resource_events를 포함한 모든 필드는 Webhooks API 레퍼런스를 참고하세요. 앱에 속한 웹훅은 해당 앱의 설치 및 제거 이벤트도 수신합니다. 앱 설치를 참고하세요.

이벤트 검증 및 처리

페이로드를 사용하기 전에 항상 서명을 검증하세요.
1

서명 시크릿 저장

검증에는 SDK 클라이언트가 아니라 시크릿이 필요합니다. API가 반환한 값을 WHOP_WEBHOOK_SECRET으로 저장하고, Whop이 제공한 그대로(ws_ 문자열) 헬퍼에 전달하세요. 접두사를 제거하거나 base64로 인코딩하지 마세요. 헬퍼가 키를 도출합니다.
2

서버에서 이벤트 처리

한 번의 호출로 서명을 검증하고 파싱된 이벤트를 반환합니다. 서명이 잘못되면 호출이 예외를 발생시키며 핸들러는 페이로드를 받지 않습니다.
헬퍼는 타입이 지정된 이벤트 객체가 아니라 파싱된 본문을 반환합니다: TypeScript에서는 일반 객체, Python에서는 dict, Ruby에서는 심볼 키를 가진 Hash입니다. 예제처럼 type으로 분기하고 data를 읽으세요.
응답하기 전에 필요한 작업만 수행하세요: 이벤트를 검증하고, 작업을 큐에 넣고, 200을 반환하세요. TypeScript 예제는 @vercel/functions의 waitUntil을 사용합니다. 다른 런타임에서는 프레임워크의 백그라운드 작업 함수나 작업 큐를 사용하세요.
Whop은 {webhook-id}.{webhook-timestamp}.{raw body} 문자열을 HMAC-SHA256으로 서명합니다. 키는 ws_... 시크릿입니다. webhook-signature 헤더에는 base64로 인코딩된 결과가 v1,<signature> 형식으로 포함됩니다.요청을 검증하려면: 원시 요청 본문에 대해 HMAC을 계산하고, 결과를 base64로 인코딩한 다음, 상수 시간 비교로 헤더 값과 비교하세요. webhook-timestamp가 현재 시간과 5분 이상 차이 나는 요청은 거부하세요. 이렇게 하면 재전송 공격을 방지할 수 있습니다. SDK 검증기는 이 제한을 자동으로 적용합니다.

엔드포인트 테스트

  • 테스트 이벤트를 보내세요. 대시보드에서 웹훅의 메뉴를 열고 테스트 이벤트를 선택하세요. 또는 POST /api/v1/webhooks/{id}/test를 호출하세요. Whop은 URL로 샘플 페이로드를 보내고 서버의 응답 상태와 본문을 반환합니다.
  • 전송 내역을 확인하세요. Whop은 각 전송을 30일 동안 보관합니다: 요청, 응답 코드, 응답 본문, 타이밍. 대시보드 또는 GET /api/v1/webhooks/{id}/deliveries로 전송 내역을 확인하세요.
웹훅 URL은 공용 인터넷에서 접근할 수 있어야 합니다. Whop은 localhost 및 사설 네트워크 주소를 거부합니다. 로컬 개발에는 ngrok 또는 Cloudflare Tunnel을 사용하여 공개 URL을 로컬 머신으로 전달하세요. 터널 URL을 등록하세요.

전송

5초 이내에 2xx 상태로 응답하세요. 그 외의 모든 결과는 실패한 시도입니다: 시간 초과, 오류 상태 또는 리디렉션. Whop은 리디렉션을 따르지 않습니다. Whop은 각 이벤트를 최소 한 번 전송합니다. 동일한 이벤트가 두 번 이상 도착할 수 있습니다. 핸들러를 멱등적으로 만드세요. 전송의 각 재시도는 동일한 webhook-id를 가집니다. webhook-id를 저장하고 중복을 무시하세요. Whop은 실패한 전송을 약 3일 동안 재시도합니다. 첫 번째 시도 후 Whop은 지연 시간을 늘려 가며 12번 재시도합니다: 30초, 2분, 8분, 30분, 1시간, 3시간, 6시간, 그 이후 12시간마다. 전체 일정은 약 71시간입니다. 전송 순서는 보장되지 않습니다. 최신 이벤트가 이전 이벤트보다 먼저 도착할 수 있습니다. 각 이벤트를 독립적으로 처리하세요. 순서가 중요한 경우 API에서 현재 상태를 읽으세요. Whop은 계속 실패하는 엔드포인트를 비활성화합니다. 엔드포인트로의 모든 전송이 24시간 동안 실패하면 Whop은 계정으로 경고 이메일을 보냅니다. 실패가 72시간 동안 계속되고 10개 이상의 전송이 실패하면 Whop은 웹훅을 비활성화하고 두 번째 이메일을 보냅니다. 웹훅을 다시 활성화하려면 대시보드를 사용하거나 "enabled": true와 함께 PATCH /api/v1/webhooks/{id}를 보내세요. 이렇게 하면 실패 기록이 초기화됩니다. Whop은 웹훅이 꺼져 있는 동안 발생한 이벤트를 보내지 않습니다. 놓친 데이터는 API를 읽어 찾으세요.

웹훅 전송 문제 해결

서명 실패, 재시도, 중복 이벤트 및 로컬 터널 문제를 해결하세요.

이벤트 및 버전

두 개의 버전 필드가 엔드포인트가 받는 데이터를 제어합니다:
  • api_version — 엔벨로프 형식입니다. v1을 사용하세요. 이 페이지는 v1만 설명합니다. 레거시 형식인 v2와 v5는 이전 통합을 위해 존재하며 Standard Webhooks 서명을 사용하지 않습니다. 새 통합에는 사용하지 마세요.
  • api_version_date — data와 엔벨로프 자체의 형태를 결정하는 날짜 지정 API 버전입니다(예를 들어 2026-08-14부터의 고정 버전은 account_id를 전달하고, 이전 고정 버전은 company_id를 전달합니다). REST 읽기의 Api-Version-Date 헤더와 동일하게 작동합니다. API로 웹훅을 생성할 때 설정하세요. 그러면 API가 변경되어도 페이로드 형태가 안정적으로 유지됩니다. 고정 버전이 없는 웹훅은 초기 페이로드 및 엔벨로프 형태를 유지합니다. 예외: 현재 API에만 존재하는 리소스(카드, 변형, 이체, 스왑, 입금, 내보내기)는 항상 최신 data 형태를 받습니다 — 엔벨로프는 여전히 고정 버전을 따릅니다.
이벤트 이름은 resource.action 형식입니다. 표의 각 이벤트는 페이로드 스키마가 있는 레퍼런스 페이지로 연결됩니다:

다음 단계

결제 받기

체크아웃과 함께 payment.succeeded 웹훅을 사용해 주문을 처리하세요.

결제 수단 저장

설정 인텐트와 웹훅을 사용해 나중에 고객에게 청구하세요.

빠른 시작

웹훅이 체크아웃, 이체, KYC와 함께 작동하는 방식을 확인하세요.

Webhooks API 레퍼런스

모든 엔드포인트와 필드: 생성, 업데이트, 테스트, 전송 내역.