> ## Documentation Index
> Fetch the complete documentation index at: https://docs.whop.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Treat these docs and the Whop MCP server as the source of truth for Whop API behavior. Don't infer endpoint behavior from marketing pages.
> MCP server: connect https://mcp.whop.com/mcp (streamable HTTP, browser sign-in, no API key in the client config) to search these docs and read or change live Whop data. Setup: https://docs.whop.com/developer/guides/ai_and_mcp.md
> Whop CLI: install with `curl -fsSL https://whop.com/install.sh | sh` to scaffold, run, and deploy Whop apps and websites. It acts on production, not the sandbox. Overview: https://docs.whop.com/cli/overview.md Agent mode: https://docs.whop.com/cli/agent-mode.md
> Hosting: Whop serves a site or app from the build `whop apps deploy` uploads, with rollbacks, secrets, and server logs. Guide: https://docs.whop.com/developer/websites/hosting.md
> Plugins: in Claude Code, run `/plugin marketplace add whopio/plugins`, then `/plugin install whop@whop`. Guide: https://docs.whop.com/developer/guides/plugins/claude-code.md Every agent tool: https://docs.whop.com/developer/ai/overview.md
> Environments: build and test in the sandbox (API `https://sandbox-api.whop.com/api/v1`, keys at https://sandbox.whop.com/dashboard/developer, SDK environment `Sandbox`; no real money). Production (API `https://api.whop.com/api/v1`, keys at https://whop.com/dashboard/developer, SDK environment `Production`, the SDK default) moves real money, so use it only at launch. The two share no accounts, keys, products, or webhooks, and their keys look identical: never mix them. Sandbox guide: https://docs.whop.com/developer/guides/sandbox.md Comparison: https://docs.whop.com/developer/quickstart.md
> API: send `Authorization: Bearer <API_KEY>` from your server only, and pin a dated version with the `Api-Version-Date` header. OpenAPI spec: https://api.whop.com/api/v1/openapi.json
> Which API: build on the Current API, whose pages live under https://docs.whop.com/api-reference/ (start at https://docs.whop.com/api-reference/overview.md). Pages under /api-reference/legacy/ are the Legacy API. Use one only when https://docs.whop.com/api-reference/stability.md lists the resource as Legacy-only.

# 서버 사이드 이벤트 보내기

> 서버에서 전환 이벤트를 보내고 Whop Pixel이 이미 추적하는 방문자와 연결하세요.

Events API는 [Whop Pixel](https://docs.whop.com/ko/developer/ads/pixel.md)의 서버 사이드 버전입니다. [`POST /events`](https://docs.whop.com/ko/api-reference/events/create-event)는 픽셀이 브라우저에서 보내는 것과 같은 이벤트를 받으므로, 픽셀이 실행되지 않는 곳에서 발생한 전환을 보고할 수 있습니다. CRM에서 성사된 판매, 자체 백엔드에서의 결제, 양식이나 예약 도구의 웹훅, 담당자가 예약 완료로 표시한 통화 등이 여기에 해당합니다.

> [!NOTE]
>
> **시작하기 전에** 세 가지가 필요합니다:
>
> * 퍼널의 모든 페이지에 설치된 [Whop Pixel](https://docs.whop.com/ko/developer/ads/pixel.md). 이 가이드에서 전달하는 방문자 ID를 생성합니다.
> * `event:create` 권한이 있는 API 키. **Account API Keys**에서 [키를 생성](https://whop.com/dashboard/developer)하고 서버에 보관하세요. 절대 브라우저 코드에 넣지 마세요.
> * 계정 ID. 대시보드 URL에서 `dashboard/` 뒤에 오는 `biz_`로 시작하는 부분입니다.

## Events API를 사용해야 하는 경우

대부분의 통합에는 필요하지 않습니다. 픽셀은 이미 브라우저에서 발생하는 모든 것을 보고하며, 방문자 ID, IP 주소, 사용자 에이전트를 자동으로 채웁니다. 전환이 발생했다는 사실을 서버만 알고 있는 경우에만 Events API를 사용하세요. 액션이 발생하는 곳에서 `whop.track` 호출을 실행할 수 있다면 그것을 대신 사용하세요.

## 서버 이벤트 보내기

### 1. 브라우저에서 방문자 ID 읽기

픽셀은 각 방문자의 ID를 도메인의 `_wuid`라는 퍼스트 파티 쿠키에 저장하고, 같은 키로 `localStorage`에도 복제합니다. 값은 `wuid_k3j9x2m1p8q4r7s0t5u6`과 같은 형태입니다. 페이지 로드 시점이 아니라 나중에 보고할 액션을 방문자가 수행하는 순간에 읽으세요. 쿠키는 페이지에서 픽셀 스니펫이 실행된 후에만 존재합니다.

```html Read the visitor ID theme={null}
<script>
  function whopVisitorId() {
    const match = document.cookie.match(/(?:^|;\s*)_wuid=([^;]*)/);
    if (match) return match[1];
    try {
      return localStorage.getItem("_wuid") || undefined;
    } catch {
      return undefined;
    }
  }
</script>
```

각 서브도메인은 자체 `_wuid`를 가집니다. 픽셀이 이를 한 사람으로 연결하므로, 전달이 일어나는 페이지에 있는 쿠키를 읽으세요.

### 2. 액션과 함께 서버로 보내기

액션을 백엔드로 전달하는 기존 요청(양식 제출, 결제 호출, 가입 요청)에 방문자 ID를 첨부하세요. 동시에 페이지 URL도 캡처하세요. 페이지 URL에는 서버가 달리 볼 수 없는 UTM과 클릭 ID가 포함되어 있습니다.

```html Hidden form fields theme={null}
<form id="quote-form" action="/api/quotes" method="post">
  <input type="email" name="email" required />
  <input type="hidden" name="whop_visitor_id" />
  <input type="hidden" name="whop_page_url" />
  <button type="submit">Get a quote</button>
</form>

<script>
  document.getElementById("quote-form").addEventListener("submit", (e) => {
    e.target.whop_visitor_id.value = whopVisitorId() || "";
    e.target.whop_page_url.value = location.href;
  });
</script>
```

```html JSON request theme={null}
<script>
  async function submitQuote(email) {
    await fetch("/api/quotes", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        email,
        whop_visitor_id: whopVisitorId(),
        whop_page_url: location.href,
      }),
    });
  }
</script>
```

```javascript Same-host backend (Node) theme={null}
app.post("/api/quotes", (req, res) => {
  const lead = {
    email: req.body.email,
    whop_visitor_id: req.cookies._wuid,
    whop_page_url: req.body.whop_page_url,
  };
  // Store the lead, then respond.
});
```

백엔드가 페이지와 같은 호스트에서 응답한다면 `_wuid` 쿠키가 요청과 함께 자동으로 도착합니다. 브라우저에서 보내는 대신 거기서 읽으세요. 쿠키는 해당 호스트에만 설정되므로 `example.com`에서 `api.example.com`으로 보내는 요청에는 포함되지 않습니다.

서버는 이미 해당 요청에서 방문자의 IP 주소와 사용자 에이전트를 볼 수 있습니다. 둘 다 보관하세요.

### 3. 고객 레코드에 저장

방문자 ID, 페이지 URL, IP 주소, 사용자 에이전트를 리드, 고객 또는 주문에 저장하세요. 보고하는 전환은 방문 후 며칠이 지나서 발생할 수 있습니다. 영업팀이 다음 주에 성사시키는 거래도 귀속을 위해 원래 방문의 방문자 ID가 필요합니다. Whop은 최대 28일 전의 이벤트까지 받습니다.

### 4. 이벤트 보내기

API 키를 사용하여 서버에서 이벤트를 보내세요. 이 예시는 광고를 통해 도착하여 견적 양식을 작성한 후 CRM에서 적격 판정을 받은 방문자의 리드를 보고합니다.

```bash cURL theme={null}
curl -X POST https://api.whop.com/api/v1/events \
  -H "Authorization: Bearer $WHOP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "biz_xxxxxxxxxxxxx",
    "event_name": "lead",
    "event_id": "lead_8f21c0",
    "event_time": "2026-09-03T14:32:11Z",
    "action_source": "website",
    "url": "https://example.com/quote?utm_meta_ad_id=120215678901234567&utm_meta_adset_id=120215678901234566&utm_meta_campaign_id=120215678901234565&utm_source=fb&utm_placement=Facebook_Mobile_Feed&utm_medium=paid_social&utm_content=Ceramic%20coating%20reel&utm_adset=Austin%20SUV%20owners&wacid=adcamp_xxxxxxxxxx&wasid=adgrp_xxxxxxxxxxx&waid=ad_xxxxxxxxxxxxx&fbclid=IwAR0example",
    "user": {
      "anonymous_id": "wuid_k3j9x2m1p8q4r7s0t5u6",
      "email": "amara@example.com",
      "phone": "+15125550137",
      "first_name": "Amara",
      "last_name": "Okafor",
      "external_id": "crm_8842"
    },
    "context": {
      "ip_address": "203.0.113.42",
      "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_5 like Mac OS X) AppleWebKit/605.1.15",
      "fbclid": "IwAR0example",
      "utm_source": "fb"
    }
  }'
```

```typescript TypeScript theme={null}
import { WhopClient } from "@whop/sdk";

const client = new WhopClient({ token: process.env.WHOP_API_KEY });

await client.events.create({
  account_id: "biz_xxxxxxxxxxxxx",
  event_name: "lead",
  event_id: "lead_8f21c0",
  event_time: "2026-09-03T14:32:11Z",
  action_source: "website",
  url: "https://example.com/quote?utm_meta_ad_id=120215678901234567&utm_meta_adset_id=120215678901234566&utm_meta_campaign_id=120215678901234565&utm_source=fb&utm_placement=Facebook_Mobile_Feed&utm_medium=paid_social&utm_content=Ceramic%20coating%20reel&utm_adset=Austin%20SUV%20owners&wacid=adcamp_xxxxxxxxxx&wasid=adgrp_xxxxxxxxxxx&waid=ad_xxxxxxxxxxxxx&fbclid=IwAR0example",
  user: {
    anonymous_id: "wuid_k3j9x2m1p8q4r7s0t5u6",
    email: "amara@example.com",
    phone: "+15125550137",
    first_name: "Amara",
    last_name: "Okafor",
    external_id: "crm_8842",
  },
  context: {
    ip_address: "203.0.113.42",
    user_agent: "Mozilla/5.0 (iPhone; CPU iPhone OS 17_5 like Mac OS X) AppleWebKit/605.1.15",
    fbclid: "IwAR0example",
    utm_source: "fb",
  },
});
```

```python Python theme={null}
import os
from whop_sdk import Whop

client = Whop(token=os.environ["WHOP_API_KEY"])

client.events.create(
    account_id="biz_xxxxxxxxxxxxx",
    event_name="lead",
    event_id="lead_8f21c0",
    event_time="2026-09-03T14:32:11Z",
    action_source="website",
    url="https://example.com/quote?utm_meta_ad_id=120215678901234567&utm_meta_adset_id=120215678901234566&utm_meta_campaign_id=120215678901234565&utm_source=fb&utm_placement=Facebook_Mobile_Feed&utm_medium=paid_social&utm_content=Ceramic%20coating%20reel&utm_adset=Austin%20SUV%20owners&wacid=adcamp_xxxxxxxxxx&wasid=adgrp_xxxxxxxxxxx&waid=ad_xxxxxxxxxxxxx&fbclid=IwAR0example",
    user={
        "anonymous_id": "wuid_k3j9x2m1p8q4r7s0t5u6",
        "email": "amara@example.com",
        "phone": "+15125550137",
        "first_name": "Amara",
        "last_name": "Okafor",
        "external_id": "crm_8842",
    },
    context={
        "ip_address": "203.0.113.42",
        "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_5 like Mac OS X) AppleWebKit/605.1.15",
        "fbclid": "IwAR0example",
        "utm_source": "fb",
    },
)
```

예시의 `url`은 방문자가 Meta에서 Whop 광고를 탭한 후 도착하는 페이지입니다. `utm_meta_ad_id`, `utm_meta_adset_id`, `utm_meta_campaign_id`는 네트워크의 ID입니다. `wacid`, `wasid`, `waid`는 Whop 캠페인, 광고 그룹, 광고 ID입니다. `utm_source`는 노출 영역(`fb`, `ig`, `msg` 또는 `an`)을, `utm_placement`는 게재 위치를, `utm_content`와 `utm_adset`은 광고 및 광고 그룹 이름을 나타내며, `fbclid`는 네트워크가 직접 추가하는 태그입니다. Whop은 이 값들로 어떤 광고가 방문을 유도했는지 판단하므로, 매개변수를 골라내지 말고 URL 전체를 저장하세요.

응답은 저장된 이벤트 ID를 반환합니다. Whop은 서로 다른 계정의 ID가 충돌하지 않도록 `event_id` 앞에 계정을 접두사로 붙입니다:

```json theme={null}
{ "id": "biz_xxxxxxxxxxxxx:lead_8f21c0" }
```

### 5. 올바른 사람에게 기록되었는지 확인

[이벤트 목록 조회](https://docs.whop.com/ko/api-reference/events/list-events.md)는 방문자 ID를 `identifier`로 받으므로, 이벤트가 합류한 전체 여정을 읽을 수 있습니다. 요청에는 `company:basic:read`와 같은 읽기 권한이 있는 키가 필요합니다.

```bash cURL theme={null}
curl "https://api.whop.com/api/v1/events?identifier=wuid_k3j9x2m1p8q4r7s0t5u6" \
  -H "Authorization: Bearer $WHOP_API_KEY"
```

서버 이벤트는 같은 `person_id`로 픽셀의 페이지 조회 옆에 표시됩니다. 페이지 조회는 있는데 이벤트가 없다면 방문자 ID가 일치하지 않은 것입니다. [문제 해결](#troubleshooting)을 참조하세요. 이벤트는 대시보드의 [Events 페이지](https://whop.com/dashboard/events)에도 표시됩니다.

## 귀속을 결정하는 매개변수

`account_id`와 `event_name`만 필수입니다. 나머지 페이로드가 이벤트를 귀속 가능하게 만들므로, 이것들도 필수로 취급하세요.

| 필드 | 보낼 내용 |
| - | - |
| `user.anonymous_id` | `_wuid` 쿠키의 방문자 ID. 서버 이벤트를 광고에서 온 브라우저 세션과 연결하는 유일한 필드입니다. 이 값이 없으면 Whop은 이메일이나 전화번호로만 매칭할 수 있습니다. |
| `user.email`, `user.phone` | 고객이 입력한 그대로의 일반 텍스트. 픽셀이 이전에 캡처한 경우 Whop은 이 값으로 매칭합니다. 해시된 이메일은 유효하지 않은 값으로 버려집니다. |
| `user.first_name`, `user.last_name`, `user.external_id` | 그 외에 알고 있는 정보. `external_id`는 자체 고객 ID입니다. |
| `event_id` | 이 하나의 액션에 대한 고정 ID: 주문 번호, 거래 ID 또는 양식 제출 ID. Whop은 각 `event_name`과 `event_id` 쌍을 한 번만 저장하므로, 재시도나 같은 전환의 두 번째 사본은 하나의 이벤트로 합쳐집니다. [중복 이벤트 방지](#avoid-duplicate-events)를 참조하세요. |
| `event_time` | 액션이 발생한 시점(ISO 8601 타임스탬프). 기본값은 현재입니다. Whop은 28일보다 오래된 이벤트를 거부하고 미래 타임스탬프는 현재로 조정합니다. 작업이 실행된 시간이 아닌 실제 시간을 보내세요. |
| `value`, `currency` | 금액과 `usd` 같은 소문자 ISO 4217 코드. 대부분의 이벤트에서는 선택 사항입니다. `purchase`에서는 필수이며 0보다 커야 합니다. |
| `url` | 액션이 시작될 때 방문자가 있던 페이지(쿼리 문자열 포함). Whop 광고를 통한 방문의 경우, 그 쿼리 문자열에 Whop이 캠페인, 광고 그룹, 광고를 판단하는 ID가 포함되어 있습니다. |
| `context.ip_address`, `context.user_agent` | 원래 브라우저 요청에서 복사한 방문자의 값. Whop은 인증되지 않은 브라우저 호출에서만 연결에서 이 값을 읽습니다. 서버 호출에서는 아무것도 추론되지 않으므로, 이 값이 없는 이벤트에는 기기나 위치 신호가 없습니다. |
| `context.fbclid`, `context.gclid`, `context.ttclid`, `context.utm_*` | 저장해 둔 경우 랜딩 페이지 URL의 광고 네트워크 ID와 `utm_*` 매개변수. |
| `context.fbp`, `context.fbc` | 캡처해 둔 경우 방문자 브라우저의 Meta `_fbp` 및 `_fbc` 쿠키 값. |
| `action_source` | 액션이 발생한 곳: `website`, `app`, `email`, `phone_call`, `chat`, `physical_store`, `system_generated`, `business_messaging` 또는 `other`. |

전체 요청 스키마는 [이벤트 생성](https://docs.whop.com/ko/api-reference/events/create-event.md) 레퍼런스 페이지에 있습니다.

## 이벤트 이름 지정

픽셀과 같은 이름을 사용하세요. 서버에서 보고한 `lead`는 픽셀이 보고한 `lead`와 같은 이벤트로 기록되므로, 리드를 기준으로 평가되는 캠페인의 결과에 반영됩니다.

| 이벤트 | 보내는 시점 |
| - | - |
| `lead` | 방문자가 연락처 정보나 옵트인 양식을 제출할 때 |
| `schedule` | 방문자가 통화나 약속을 예약할 때 |
| `submit_application` | 방문자가 신청서를 제출할 때 |
| `contact` | 방문자가 대화나 연락 요청을 시작할 때 |
| `complete_registration` | 가입 또는 등록이 완료될 때 |
| `view_content` | 방문자가 주요 페이지나 콘텐츠를 볼 때 |
| `add_to_cart` | 방문자가 장바구니에 항목을 추가할 때 |
| `initiate_checkout` | 방문자가 결제 단계에 도달할 때 |
| `purchase` | 자체 결제에서 판매가 완료될 때. `value`가 필수입니다 |

그 외의 `event_name`은 해당 이름의 커스텀 이벤트가 됩니다. 이름은 짧고 일관되게 유지하고, 소수의 이름을 재사용하세요.

```json Custom event theme={null}
{ "account_id": "biz_xxxxxxxxxxxxx", "event_name": "deal_closed", "value": 2400, "currency": "usd" }
```

> [!WARNING]
>
> Whop이 처리한 판매에 대해서는 절대 `purchase`를 보내지 마세요. Whop은 자체 결제에서 발생한 모든 결제, 구매, 구독, 체험을 자동으로 기록하고 광고 네트워크에 보고합니다. Whop이 볼 수 없는 이벤트만 보내세요.

## 중복 이벤트 방지

같은 전환이 브라우저와 서버 양쪽에서 Whop에 도달할 수 있다면, 같은 `event_name`과 같은 `event_id`로 양쪽에서 보내세요. Whop은 하나의 사본만 유지합니다. 양식이 제출 시 `whop.track("lead", { event_id })`를 실행하고 백엔드가 검증 후 같은 리드를 다시 보고하는 경우 가장 안전한 설정입니다.

`event_id`는 액션의 유형이 아니라 하나의 액션을 식별합니다. 모든 리드에는 고유한 ID가 필요합니다. 전송 시점에 만들어낸 값은 매번 새로운 값이므로 아무것도 막지 못합니다. 시스템에 이미 있는 해당 액션의 ID를 사용하세요.

## 문제 해결

**이벤트는 저장되었지만 광고에 귀속되지 않습니다.** 이벤트에 `user.anonymous_id`가 없거나, 픽셀이 사용한 적 없는 값이 포함되었습니다. 일반적인 원인은 픽셀 스니펫이 실행되기 전에 쿠키를 읽었거나, 픽셀이 없는 도메인에서 읽었거나, 잘못된 레코드에 방문자 ID를 저장한 경우입니다. 해당 방문자 ID의 이벤트를 나열하여 수정을 확인하세요. 픽셀의 페이지 조회가 이벤트와 같은 `identifier` 아래에 표시되어야 합니다.

**`event_time`에 대한 메시지와 함께 `400`.** 타임스탬프가 28일보다 오래되었습니다. 이벤트가 발생한 시점에 더 가깝게 보내거나 버리세요.

**`purchase` 이벤트에서 `400`.** `value`가 없거나 0보다 크지 않습니다. 광고 네트워크는 금액이 없는 판매를 기준으로 최적화할 수 없으므로 Whop이 거부합니다.

**`401` 또는 `403`.** 키가 없거나, `event:create` 권한이 없거나, `account_id`와 다른 계정에 속합니다. 프로덕션 키는 `https://api.whop.com/api/v1`을 사용합니다.
