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

# Server-side events verzenden

> Verstuur conversie-events vanaf je server en koppel ze aan de bezoeker die de Whop Pixel al volgt.

De Events API is de server-side tegenhanger van de [Whop Pixel](https://docs.whop.com/nl/developer/ads/pixel.md). [`POST /events`](https://docs.whop.com/nl/api-reference/events/create-event) accepteert dezelfde events die de pixel vanuit de browser verstuurt, zodat je conversies kunt rapporteren die plaatsvinden waar geen pixel draait. Denk aan een verkoop die in je CRM is afgesloten, een betaling op je eigen backend, een webhook van een formulier- of boekingstool, of een gesprek dat een medewerker als geboekt markeert.

> [!NOTE]
>
> **Voordat je begint**, heb je drie dingen nodig:
>
> * De [Whop Pixel](https://docs.whop.com/nl/developer/ads/pixel.md), geïnstalleerd op elke pagina van je funnel. Deze maakt de bezoekers-ID aan die deze gids doorgeeft.
> * Een API-sleutel met de machtiging `event:create`. [Maak er een aan](https://whop.com/dashboard/developer) onder **Account API Keys** en bewaar deze op je server. Zet hem nooit in browsercode.
> * Je account-ID, het deel van je dashboard-URL na `dashboard/` dat begint met `biz_`.

## Wanneer gebruik je de Events API

De meeste integraties hebben dit niet nodig. De pixel rapporteert al alles wat er in de browser gebeurt, en vult zelf de bezoekers-ID, het IP-adres en de user agent in. Gebruik de Events API alleen wanneer je server de enige plek is die weet dat er een conversie heeft plaatsgevonden. Als een `whop.track`-aanroep kan worden uitgevoerd waar de actie plaatsvindt, gebruik die dan.

## Een server-event verzenden

### 1. Lees de bezoekers-ID in de browser

De pixel slaat de ID van elke bezoeker op in een first-party cookie met de naam `_wuid` op je domein, en spiegelt deze naar `localStorage` onder dezelfde sleutel. De waarde ziet eruit als `wuid_k3j9x2m1p8q4r7s0t5u6`. Lees deze uit op het moment dat de bezoeker de actie uitvoert die je later rapporteert, niet bij het laden van de pagina. De cookie bestaat pas nadat het pixelfragment op de pagina is uitgevoerd.

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

Elk subdomein krijgt zijn eigen `_wuid`. De pixel koppelt ze aan één persoon, dus lees de cookie die aanwezig is op de pagina waar de overdracht plaatsvindt.

### 2. Stuur deze met de actie naar je server

Voeg de bezoekers-ID toe aan het verzoek dat de actie al naar je backend brengt: een formulierinzending, een checkout-aanroep, een aanmeldverzoek. Leg tegelijkertijd de pagina-URL vast. Die bevat de UTM's en klik-ID's die je server anders niet kan zien.

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

Als je backend antwoordt op dezelfde host als de pagina, komt de `_wuid`-cookie vanzelf mee met het verzoek. Lees hem daar uit in plaats van hem vanuit de browser te versturen. De cookie is alleen voor die host ingesteld, dus een verzoek van `example.com` naar `api.example.com` bevat hem niet.

Je server ziet bij dat verzoek al het IP-adres en de user agent van de bezoeker. Bewaar beide.

### 3. Sla deze op bij het klantrecord

Sla de bezoekers-ID, pagina-URL, het IP-adres en de user agent op bij de lead, klant of bestelling. De conversie die je rapporteert kan dagen na het bezoek plaatsvinden. Een deal die je salesteam volgende week sluit, heeft nog steeds de bezoekers-ID van het oorspronkelijke bezoek nodig voor toeschrijving. Whop accepteert events tot 28 dagen oud.

### 4. Verstuur het event

Verstuur het event vanaf je server met je API-sleutel. Het voorbeeld rapporteert een lead van een bezoeker die via een advertentie binnenkwam, een offerteformulier invulde en daarna in een CRM werd gekwalificeerd.

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

De `url` in het voorbeeld is waar een bezoeker terechtkomt na het tikken op een Whop-advertentie op Meta. `utm_meta_ad_id`, `utm_meta_adset_id` en `utm_meta_campaign_id` zijn de ID's van het netwerk. `wacid`, `wasid` en `waid` zijn de campagne-, advertentiegroep- en advertentie-ID's van Whop. `utm_source` noemt het oppervlak (`fb`, `ig`, `msg` of `an`), `utm_placement` de plaatsing, `utm_content` en `utm_adset` de namen van de advertentie en advertentiegroep, en `fbclid` is de tag die het netwerk zelf toevoegt. Whop bepaalt hieruit welke advertentie het bezoek heeft opgeleverd, dus sla de volledige URL op in plaats van er parameters uit te kiezen.

De respons retourneert de opgeslagen event-ID. Whop zet het account voor je `event_id`, zodat ID's van verschillende accounts nooit botsen:

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

### 5. Controleer of het bij de juiste persoon is beland

[List Events](https://docs.whop.com/nl/api-reference/events/list-events.md) accepteert een bezoekers-ID als `identifier`, zodat je het volledige traject kunt lezen waaraan het event is toegevoegd. Het verzoek heeft een sleutel nodig met een leesmachtiging zoals `company:basic:read`.

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

Je server-event verschijnt naast de paginaweergaven van de pixel met dezelfde `person_id`. Als de paginaweergaven er wel zijn maar je event niet, kwam de bezoekers-ID niet overeen. Zie [Probleemoplossing](#troubleshooting). Het event verschijnt ook op de [Events-pagina](https://whop.com/dashboard/events) in je dashboard.

## Parameters die de toeschrijving bepalen

Alleen `account_id` en `event_name` zijn verplicht. De rest van de payload maakt het event toeschrijfbaar, dus behandel deze ook als verplicht.

| Veld | Wat je verstuurt |
| - | - |
| `user.anonymous_id` | De bezoekers-ID uit de `_wuid`-cookie. Dit is het enige veld dat een server-event koppelt aan de browsersessie die van de advertentie kwam. Zonder dit veld kan Whop alleen matchen op e-mail of telefoon. |
| `user.email`, `user.phone` | Platte tekst, precies zoals de klant ze heeft ingevoerd. Whop matcht hierop wanneer de pixel ze eerder heeft vastgelegd. Een gehasht e-mailadres wordt als ongeldig verworpen. |
| `user.first_name`, `user.last_name`, `user.external_id` | Wat je verder nog weet. `external_id` is je eigen klant-ID. |
| `event_id` | Een stabiele ID voor deze ene actie: je bestelnummer, deal-ID of formulierinzending-ID. Whop slaat elk paar van `event_name` en `event_id` één keer op, dus een nieuwe poging of een tweede kopie van dezelfde conversie wordt samengevoegd tot één event. Zie [Dubbele events voorkomen](#avoid-duplicate-events). |
| `event_time` | Wanneer de actie plaatsvond, als ISO 8601-tijdstempel. Standaard nu. Whop weigert alles wat ouder is dan 28 dagen en zet tijdstempels in de toekomst op nu. Stuur het echte tijdstip, niet het tijdstip waarop je job draaide. |
| `value`, `currency` | De geldwaarde en de ISO 4217-code in kleine letters, zoals `usd`. Optioneel bij de meeste events. Verplicht en groter dan nul bij `purchase`. |
| `url` | De pagina waarop de bezoeker zich bevond toen de actie begon, inclusief de querystring. Bij een bezoek via een Whop-advertentie bevat die querystring de ID's waaruit Whop de campagne, advertentiegroep en advertentie bepaalt. |
| `context.ip_address`, `context.user_agent` | Die van de bezoeker, gekopieerd uit diens oorspronkelijke browserverzoek. Whop leest deze alleen uit de verbinding bij niet-geauthenticeerde browseraanroepen. Bij een serveraanroep wordt niets afgeleid, dus een event zonder deze velden heeft geen apparaat- of locatiesignalen. |
| `context.fbclid`, `context.gclid`, `context.ttclid`, `context.utm_*` | De ID's van het advertentienetwerk en de `utm_*`-parameters uit de URL van de landingspagina, als je die hebt opgeslagen. |
| `context.fbp`, `context.fbc` | De waarden van de Meta-cookies `_fbp` en `_fbc` uit de browser van de bezoeker, als je die hebt vastgelegd. |
| `action_source` | Waar de actie plaatsvond: `website`, `app`, `email`, `phone_call`, `chat`, `physical_store`, `system_generated`, `business_messaging` of `other`. |

Het volledige request-schema staat op de referentiepagina [Create Event](https://docs.whop.com/nl/api-reference/events/create-event.md).

## Het event een naam geven

Gebruik dezelfde namen als de pixel. Een `lead` die je vanaf je server rapporteert, komt binnen als hetzelfde event als een `lead` die de pixel rapporteert, dus telt mee voor de resultaten van een campagne die op leads wordt beoordeeld.

| Event | Wanneer je het verstuurt |
| - | - |
| `lead` | Een bezoeker dient contactgegevens of een opt-in-formulier in |
| `schedule` | Een bezoeker boekt een gesprek of afspraak |
| `submit_application` | Een bezoeker dient een aanvraag in |
| `contact` | Een bezoeker start een gesprek of contactverzoek |
| `complete_registration` | Een aanmelding of registratie wordt voltooid |
| `view_content` | Een bezoeker bekijkt een belangrijke pagina of content |
| `add_to_cart` | Een bezoeker voegt een item toe aan een winkelwagen |
| `initiate_checkout` | Een bezoeker bereikt de checkout |
| `purchase` | Een verkoop wordt voltooid in je eigen checkout. `value` is verplicht |

Elke andere `event_name` wordt een aangepast event onder die naam. Houd namen kort en stabiel, en hergebruik een kleine set.

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

> [!WARNING]
>
> Verstuur nooit `purchase` voor een verkoop die Whop heeft verwerkt. Whop registreert elke checkout, aankoop, elk abonnement en elke proefperiode in de eigen checkout automatisch en rapporteert deze aan het advertentienetwerk. Verstuur alleen events die Whop niet kan zien.

## Dubbele events voorkomen

Als dezelfde conversie Whop zowel vanuit de browser als vanaf je server kan bereiken, verstuur haar dan vanaf beide met dezelfde `event_name` en dezelfde `event_id`. Whop bewaart één kopie. Dit is de veiligste setup wanneer een formulier bij verzenden `whop.track("lead", { event_id })` uitvoert en je backend dezelfde lead na validatie opnieuw rapporteert.

De `event_id` identificeert één actie, niet het type actie. Elke lead heeft een eigen ID nodig. Een waarde die op het moment van verzenden wordt bedacht, is elke keer nieuw en voorkomt dus niets. Gebruik een ID die je systeem al voor die ene actie heeft.

## Probleemoplossing

**Het event is opgeslagen maar niet aan een advertentie toegeschreven.** Het event bevatte geen `user.anonymous_id`, of een waarde die de pixel nooit heeft gebruikt. Gebruikelijke oorzaken zijn het uitlezen van de cookie voordat het pixelfragment was uitgevoerd, het uitlezen op een domein zonder de pixel, of het opslaan van de bezoekers-ID bij het verkeerde record. Bevestig de oplossing door events voor die bezoekers-ID op te vragen. De paginaweergaven van de pixel moeten onder dezelfde `identifier` verschijnen als je event.

**`400` met een melding over `event_time`.** De tijdstempel is meer dan 28 dagen oud. Verstuur het event dichter bij het moment waarop het plaatsvindt, of laat het vallen.

**`400` bij een `purchase`-event.** `value` ontbreekt of is niet groter dan nul. Advertentienetwerken kunnen niet optimaliseren op een verkoop zonder bedrag, dus Whop weigert het event.

**`401` of `403`.** De sleutel ontbreekt, mist `event:create`, of hoort bij een ander account dan `account_id`. Productiesleutels gebruiken `https://api.whop.com/api/v1`.


## Related topics

- [Create Event](https://docs.whop.com/nl/api-reference/events/create-event.md)
- [PixelSetupElement](https://docs.whop.com/nl/elements/latest/websites/pixel-setup.md)
- [OAuth](https://docs.whop.com/nl/developer/guides/oauth.md)
