> ## 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.

# Sunucu Tarafı Olayları Gönderin

> Dönüşüm olaylarını sunucunuzdan gönderin ve bunları Whop Pixel'in zaten izlediği ziyaretçiye bağlayın.

Events API, [Whop Pixel](https://docs.whop.com/tr/developer/ads/pixel.md)'in sunucu tarafındaki karşılığıdır. [`POST /events`](https://docs.whop.com/tr/api-reference/events/create-event), pikselin tarayıcıdan gönderdiği olayların aynısını kabul eder; böylece hiçbir pikselin çalışmadığı yerlerde gerçekleşen dönüşümleri raporlayabilirsiniz. Bu, CRM'inizde kapanan bir satışı, kendi arka ucunuzdaki bir ödemeyi, bir form veya rezervasyon aracından gelen bir webhook'u ya da bir temsilcinin rezerve edildi olarak işaretlediği bir görüşmeyi kapsar.

> [!NOTE]
>
> **Başlamadan önce** üç şeye ihtiyacınız vardır:
>
> * Hunizinizin her sayfasına yüklenmiş [Whop Pixel](https://docs.whop.com/tr/developer/ads/pixel.md). Bu kılavuzun ilettiği ziyaretçi kimliğini o oluşturur.
> * `event:create` iznine sahip bir API anahtarı. **Account API Keys** altında [bir tane oluşturun](https://whop.com/dashboard/developer) ve sunucunuzda saklayın. Asla tarayıcı koduna koymayın.
> * Hesap kimliğiniz; panel URL'nizde `dashboard/` sonrasında gelen ve `biz_` ile başlayan kısım.

## Events API ne zaman kullanılır

Çoğu entegrasyonun buna ihtiyacı yoktur. Piksel, tarayıcıda gerçekleşen her şeyi zaten raporlar ve ziyaretçi kimliğini, IP adresini ve kullanıcı aracısını kendisi doldurur. Events API'yi yalnızca bir dönüşümün gerçekleştiğini bilen tek yer sunucunuz olduğunda kullanın. Eylemin gerçekleştiği yerde bir `whop.track` çağrısı tetiklenebiliyorsa bunun yerine onu kullanın.

## Bir sunucu olayı gönderin

### 1. Ziyaretçi kimliğini tarayıcıda okuyun

Piksel, her ziyaretçinin kimliğini alan adınızda `_wuid` adlı birinci taraf bir çerezde saklar ve aynı anahtar altında `localStorage` içine yansıtır. Değer `wuid_k3j9x2m1p8q4r7s0t5u6` gibi görünür. Bunu sayfa yüklendiğinde değil, ziyaretçinin daha sonra raporlayacağınız eylemi gerçekleştirdiği anda okuyun. Çerez yalnızca piksel kod parçacığı sayfada çalıştıktan sonra mevcut olur.

```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>
```

Her alt alan adı kendi `_wuid` değerini alır. Piksel bunları tek bir kişiye bağlar, bu nedenle aktarımın gerçekleştiği sayfada hangi çerez varsa onu okuyun.

### 2. Eylemle birlikte sunucunuza gönderin

Ziyaretçi kimliğini, eylemi arka ucunuza zaten taşıyan isteğe ekleyin: bir form gönderimi, bir ödeme çağrısı, bir kayıt isteği. Aynı anda sayfa URL'sini de yakalayın. Bu URL, sunucunuzun başka türlü göremeyeceği UTM'leri ve tıklama kimliklerini taşır.

```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.
});
```

Arka ucunuz sayfayla aynı ana makinede yanıt veriyorsa, `_wuid` çerezi istekle birlikte kendiliğinden gelir. Tarayıcıdan göndermek yerine orada okuyun. Çerez yalnızca o ana makine için ayarlanır, bu nedenle `example.com` adresinden `api.example.com` adresine yapılan bir istek onu taşımaz.

Sunucunuz o istekte ziyaretçinin IP adresini ve kullanıcı aracısını zaten görür. İkisini de saklayın.

### 3. Müşteri kaydında saklayın

Ziyaretçi kimliğini, sayfa URL'sini, IP adresini ve kullanıcı aracısını potansiyel müşteri, müşteri veya sipariş kaydına kaydedin. Raporladığınız dönüşüm, ziyaretten günler sonra gerçekleşebilir. Satış ekibinizin gelecek hafta kapattığı bir anlaşmanın atfedilebilmesi için yine de orijinal ziyaretteki ziyaretçi kimliğine ihtiyacı vardır. Whop 28 güne kadar eski olayları kabul eder.

### 4. Olayı gönderin

Olayı API anahtarınızla sunucunuzdan gönderin. Örnek, bir reklamdan gelen, bir teklif formu dolduran ve ardından bir CRM'de nitelikli hale getirilen bir ziyaretçiden gelen potansiyel müşteriyi raporlar.

```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",
    },
)
```

Örnekteki `url`, bir ziyaretçinin Meta'daki bir Whop reklamına dokunduktan sonra ulaştığı adrestir. `utm_meta_ad_id`, `utm_meta_adset_id` ve `utm_meta_campaign_id` ağın kimlikleridir. `wacid`, `wasid` ve `waid` Whop kampanya, reklam grubu ve reklam kimlikleridir. `utm_source` yüzeyi (`fb`, `ig`, `msg` veya `an`), `utm_placement` yerleşimi, `utm_content` ve `utm_adset` reklam ve reklam grubu adlarını belirtir; `fbclid` ise ağın kendisinin eklediği etikettir. Whop, ziyareti hangi reklamın sağladığını bunlardan çözümler, bu nedenle URL'den parametre seçmek yerine URL'yi bütün olarak saklayın.

Yanıt, saklanan olay kimliğini döndürür. Whop, farklı hesaplardan gelen kimliklerin asla çakışmaması için `event_id` değerinizin önüne hesabı ekler:

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

### 5. Doğru kişiye ulaştığını doğrulayın

[Olayları Listele](https://docs.whop.com/tr/api-reference/events/list-events.md) bir ziyaretçi kimliğini `identifier` olarak kabul eder, böylece olayın katıldığı yolculuğun tamamını okuyabilirsiniz. İstek, `company:basic:read` gibi bir okuma iznine sahip bir anahtar gerektirir.

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

Sunucu olayınız, pikselin sayfa görüntülemelerinin yanında aynı `person_id` ile görünür. Sayfa görüntülemeleri oradaysa ancak olayınız yoksa, ziyaretçi kimliği eşleşmemiştir. Bkz. [Sorun giderme](#troubleshooting). Olay ayrıca panelinizdeki [Events sayfasında](https://whop.com/dashboard/events) da görünür.

## Atfı belirleyen parametreler

Yalnızca `account_id` ve `event_name` zorunludur. Yükün geri kalanı olayı atfedilebilir kılan şeydir, bu nedenle bunları da zorunlu olarak değerlendirin.

| Alan | Ne gönderilmeli |
| - | - |
| `user.anonymous_id` | `_wuid` çerezindeki ziyaretçi kimliği. Bir sunucu olayını reklamdan gelen tarayıcı oturumuna bağlayan tek alan budur. Bu olmadan Whop yalnızca e-posta veya telefonla eşleştirme yapabilir. |
| `user.email`, `user.phone` | Düz metin, tam olarak müşterinin girdiği şekilde. Whop, piksel bunları daha önce yakaladıysa bunlarla eşleştirme yapar. Karma (hash) uygulanmış bir e-posta geçersiz olarak atılır. |
| `user.first_name`, `user.last_name`, `user.external_id` | Bildiğiniz diğer her şey. `external_id` kendi müşteri kimliğinizdir. |
| `event_id` | Bu tek eylem için sabit bir kimlik: sipariş numaranız, anlaşma kimliğiniz veya form gönderim kimliğiniz. Whop her `event_name` ve `event_id` çiftini bir kez saklar; böylece bir yeniden deneme veya aynı dönüşümün ikinci bir kopyası tek bir olayda birleşir. Bkz. [Yinelenen olaylardan kaçının](#avoid-duplicate-events). |
| `event_time` | Eylemin gerçekleştiği zaman, ISO 8601 zaman damgası olarak. Varsayılan olarak şimdidir. Whop 28 günden eski her şeyi reddeder ve gelecekteki zaman damgalarını şimdiye sabitler. İşinizin çalıştığı zamanı değil, gerçek zamanı gönderin. |
| `value`, `currency` | Parasal değer ve onun küçük harfli ISO 4217 kodu, örneğin `usd`. Çoğu olayda isteğe bağlıdır. `purchase` olayında zorunludur ve sıfırdan büyük olmalıdır. |
| `url` | Eylem başladığında ziyaretçinin bulunduğu sayfa, sorgu dizesi dahil. Bir Whop reklamından gelen ziyarette bu sorgu dizesi, Whop'un kampanyayı, reklam grubunu ve reklamı çözümlediği kimlikleri taşır. |
| `context.ip_address`, `context.user_agent` | Ziyaretçinin değerleri, orijinal tarayıcı isteğinden kopyalanmış. Whop bunları yalnızca kimliği doğrulanmamış tarayıcı çağrıları için bağlantıdan okur. Bir sunucu çağrısında hiçbir şey çıkarılmaz, bu nedenle bunlar olmadan gönderilen bir olayın cihaz veya konum sinyali yoktur. |
| `context.fbclid`, `context.gclid`, `context.ttclid`, `context.utm_*` | Sakladıysanız, açılış sayfası URL'sindeki reklam ağı kimlikleri ve `utm_*` parametreleri. |
| `context.fbp`, `context.fbc` | Yakaladıysanız, ziyaretçinin tarayıcısındaki Meta `_fbp` ve `_fbc` çerez değerleri. |
| `action_source` | Eylemin gerçekleştiği yer: `website`, `app`, `email`, `phone_call`, `chat`, `physical_store`, `system_generated`, `business_messaging` veya `other`. |

Tam istek şeması [Olay Oluştur](https://docs.whop.com/tr/api-reference/events/create-event.md) referans sayfasındadır.

## Olayı adlandırın

Pikselle aynı adları kullanın. Sunucunuzdan raporladığınız bir `lead`, pikselin raporladığı bir `lead` ile aynı olay olarak kaydedilir; böylece potansiyel müşterilere göre değerlendirilen bir kampanyanın sonuçlarına sayılır.

| Olay | Ne zaman gönderilir |
| - | - |
| `lead` | Bir ziyaretçi iletişim bilgilerini veya bir kayıt formunu gönderir |
| `schedule` | Bir ziyaretçi bir görüşme veya randevu ayarlar |
| `submit_application` | Bir ziyaretçi bir başvuru gönderir |
| `contact` | Bir ziyaretçi bir görüşme veya iletişim talebi başlatır |
| `complete_registration` | Bir kayıt veya üyelik işlemi tamamlanır |
| `view_content` | Bir ziyaretçi önemli bir sayfayı veya içeriği görüntüler |
| `add_to_cart` | Bir ziyaretçi sepete bir ürün ekler |
| `initiate_checkout` | Bir ziyaretçi ödeme adımına ulaşır |
| `purchase` | Kendi ödeme sayfanızda bir satış tamamlanır. `value` zorunludur |

Diğer herhangi bir `event_name`, o ad altında özel bir olay olur. Adları kısa ve sabit tutun ve küçük bir kümeyi yeniden kullanın.

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

> [!WARNING]
>
> Whop'un işlediği bir satış için asla `purchase` göndermeyin. Whop, kendi ödeme sayfasındaki her ödemeyi, satın almayı, aboneliği ve denemeyi otomatik olarak kaydeder ve reklam ağına raporlar. Yalnızca Whop'un göremediği olayları gönderin.

## Yinelenen olaylardan kaçının

Aynı dönüşüm Whop'a hem tarayıcıdan hem de sunucunuzdan ulaşabiliyorsa, her ikisinden de aynı `event_name` ve aynı `event_id` ile gönderin. Whop tek bir kopya tutar. Bu, bir formun gönderimde `whop.track("lead", { event_id })` tetiklediği ve arka ucunuzun aynı potansiyel müşteriyi doğruladıktan sonra yeniden raporladığı durumlarda en güvenli kurulumdur.

`event_id`, eylemin türünü değil, tek bir eylemi tanımlar. Her potansiyel müşterinin kendine ait bir kimliği olmalıdır. Gönderim anında uydurulan bir değer her seferinde yenidir, bu nedenle hiçbir şeyi engellemez. Sisteminizin o tek eylem için zaten sahip olduğu bir kimliği kullanın.

## Sorun giderme

**Olay saklanıyor ancak bir reklama atfedilmiyor.** Olay hiçbir `user.anonymous_id` taşımıyordu veya pikselin hiç kullanmadığı bir değer taşıyordu. Olağan nedenler, çerezi piksel kod parçacığı çalışmadan önce okumak, pikselin olmadığı bir alan adında okumak veya ziyaretçi kimliğini yanlış kayda kaydetmektir. Düzeltmeyi, o ziyaretçi kimliği için olayları listeleyerek doğrulayın. Pikselin sayfa görüntülemeleri, olayınızla aynı `identifier` altında görünmelidir.

**`event_time` hakkında bir mesajla `400`.** Zaman damgası 28 günden daha eskidir. Olayı gerçekleştiği zamana daha yakın gönderin veya bırakın.

**Bir `purchase` olayında `400`.** `value` eksik veya sıfırdan büyük değil. Reklam ağları tutarı olmayan bir satışa yönelik optimizasyon yapamaz, bu nedenle Whop bunu reddeder.

**`401` veya `403`.** Anahtar eksik, `event:create` iznine sahip değil veya `account_id` değerinden farklı bir hesaba ait. Üretim anahtarları `https://api.whop.com/api/v1` kullanır.


## Related topics

- [Whop Pixel'i Calendly ile kurun](https://docs.whop.com/tr/developer/ads/platforms/calendly.md)
- [Whop'ta Web Sitesi Barındırma](https://docs.whop.com/tr/developer/websites/hosting.md)
- [Whop Pixel'i kurun](https://docs.whop.com/tr/developer/ads/pixel.md)
