Send Server-Side Events

The Events API is the server-side counterpart to the Whop Pixel. POST /events accepts the same events the pixel sends from the browser, so you can report conversions that happen where no pixel runs. That covers a sale closed in your CRM, a payment on your own backend, a webhook from a form or booking tool, or a call a rep marks as booked.

Before you start, you need three things:

The Whop Pixel installed on every page of your funnel. It creates the visitor ID this guide passes along.
An API key with the event:create permission. Create one under Account API Keys, and keep it on your server. Never put it in browser code.
Your account ID, the part of your dashboard URL after dashboard/ that starts with biz_.

When to use the Events API

Most integrations don’t need this. The pixel already reports everything that happens in the browser, and it fills in the visitor ID, IP address, and user agent on its own. Use the Events API only when your server is the only place that knows a conversion happened. If a whop.track call can fire where the action happens, use that instead.

Send a server event

Read the visitor ID in the browser

The pixel stores each visitor’s ID in a first-party cookie named _wuid on your domain, and mirrors it to localStorage under the same key. The value looks like wuid_k3j9x2m1p8q4r7s0t5u6. Read it at the moment the visitor takes the action you’ll later report, not at page load. The cookie exists only after the pixel snippet has run on the page.

Read the visitor ID

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

Each subdomain gets its own _wuid. The pixel links them to one person, so read whichever cookie is on the page where the handoff happens.

Send it to your server with the action

Attach the visitor ID to whatever request already carries the action to your backend: a form post, a checkout call, a signup request. Capture the page URL at the same time. It carries the UTMs and click IDs that your server can’t see otherwise.

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

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

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

If your backend answers on the same host as the page, the _wuid cookie arrives on the request by itself. Read it there instead of sending it from the browser. The cookie is set for that host only, so a request from example.com to api.example.com doesn’t carry it.Your server already sees the visitor’s IP address and user agent on that request. Keep both.

Store it on the customer record

Save the visitor ID, page URL, IP address, and user agent on the lead, customer, or order. The conversion you report might happen days after the visit. A deal your sales team closes next week still needs the visitor ID from the original visit to attribute. Whop accepts events up to 28 days old.

Send the event

Post the event from your server with your API key. The example reports a lead from a visitor who arrived from an ad, filled out a quote form, and was then qualified in a CRM.

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&utm_whop=true&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"
    }
  }'

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&utm_whop=true&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",
  },
});

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&utm_whop=true&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",
    },
)

The url in the example is what a visitor lands on after tapping a Whop ad on Meta. utm_meta_ad_id, utm_meta_adset_id, and utm_meta_campaign_id are the network’s IDs. wacid, wasid, and waid are the Whop campaign, ad group, and ad IDs. utm_source names the surface (fb, ig, msg, or an), utm_placement the placement, utm_content and utm_adset the ad and ad group names, and fbclid is the tag the network appends itself. Whop resolves which ad drove the visit from these, so store the URL whole rather than picking parameters out of it.The response returns the stored event ID. Whop prefixes your event_id with the account so IDs from different accounts never collide:

{ "id": "biz_xxxxxxxxxxxxx:lead_8f21c0" }

Confirm it landed on the right person

List Events accepts a visitor ID as the identifier, so you can read the whole journey the event joined. The request needs a key with a read permission such as company:basic:read.

cURL

curl "https://api.whop.com/api/v1/events?identifier=wuid_k3j9x2m1p8q4r7s0t5u6" \
  -H "Authorization: Bearer $WHOP_API_KEY"

Your server event appears next to the pixel’s page views with the same person_id. If the page views are there but your event isn’t, the visitor ID didn’t match. See Troubleshooting. The event also shows up on the Events page in your dashboard.

Parameters that decide attribution

Only account_id and event_name are required. The rest of the payload is what makes the event attributable, so treat these as required too.

Field	What to send
`user.anonymous_id`	The visitor ID from the `_wuid` cookie. This is the one field that ties a server event to the browser session that came from the ad. Without it, Whop can only match on email or phone.
`user.email`, `user.phone`	Plain text, exactly as the customer entered them. Whop matches on these when the pixel captured them earlier. A hashed email is dropped as invalid.
`user.first_name`, `user.last_name`, `user.external_id`	Whatever else you know. `external_id` is your own customer ID.
`event_id`	A stable ID for this one action: your order number, deal ID, or form submission ID. Whop stores each `event_name` and `event_id` pair once, so a retry or a second copy of the same conversion collapses into one event. See Avoid duplicate events.
`event_time`	When the action happened, as an ISO 8601 timestamp. Defaults to now. Whop rejects anything older than 28 days and clamps future timestamps to now. Send the real time, not the time your job ran.
`value`, `currency`	The monetary value and its lowercase ISO 4217 code, such as `usd`. Optional on most events. Required and greater than zero on `purchase`.
`url`	The page the visitor was on when the action started, including its query string. On a visit from a Whop ad, that query string carries the IDs Whop resolves the campaign, ad group, and ad from.
`context.ip_address`, `context.user_agent`	The visitor’s, copied from their original browser request. Whop reads these from the connection only for unauthenticated browser calls. A server call gets nothing inferred, so an event without them has no device or location signals.
`context.fbclid`, `context.gclid`, `context.ttclid`, `context.utm_*`	The ad network IDs and `utm_*` parameters from the landing page URL, if you stored them.
`context.fbp`, `context.fbc`	The Meta `_fbp` and `_fbc` cookie values from the visitor’s browser, if you captured them.
`action_source`	Where the action happened: `website`, `app`, `email`, `phone_call`, `chat`, `physical_store`, `system_generated`, `business_messaging`, or `other`.

The full request schema is on the Create Event reference page.

Name the event

Use the same names as the pixel. A lead you report from your server lands as the same event as a lead the pixel reports, so it counts toward the results of a campaign judged on leads.

Event	When to send it
`lead`	A visitor submits contact info or an opt-in form
`schedule`	A visitor books a call or appointment
`submit_application`	A visitor submits an application
`contact`	A visitor starts a conversation or contact request
`complete_registration`	A signup or registration finishes
`view_content`	A visitor views a key page or piece of content
`add_to_cart`	A visitor adds an item to a cart
`purchase`	A sale completes on your own checkout. `value` is required

Any other event_name becomes a custom event under that name. Keep names short and stable, and reuse a small set.

Custom event

{ "account_id": "biz_xxxxxxxxxxxxx", "event_name": "deal_closed", "value": 2400, "currency": "usd" }

Never send purchase for a sale that Whop processed. Whop records every checkout, purchase, subscription, and trial on its own checkout automatically and reports it to the ad network. Only send events Whop can’t see.

Avoid duplicate events

If the same conversion can reach Whop from both the browser and your server, send it from both with the same event_name and the same event_id. Whop keeps one copy. This is the safest setup when a form fires whop.track("lead", { event_id }) on submit and your backend reports the same lead again after validating it. The event_id identifies one action, not the type of action. Every lead needs its own. A value made up at send time is new every time, so it stops nothing. Use an ID your system already has for that one action.

Troubleshooting

The event is stored but not attributed to an ad. The event carried no user.anonymous_id, or a value the pixel never used. The usual causes are reading the cookie before the pixel snippet ran, reading it on a domain without the pixel, or storing the visitor ID on the wrong record. Confirm the fix by listing events for that visitor ID. The pixel’s page views must show up under the same identifier as your event. 400 with a message about event_time. The timestamp is more than 28 days old. Send the event closer to when it happens, or drop it. 400 on a purchase event. value is missing or not greater than zero. Ad networks can’t optimize toward a sale with no amount, so Whop rejects it. 401 or 403. The key is missing, lacks event:create, or belongs to a different account than account_id. Production keys use https://api.whop.com/api/v1.

Integrate with Hosting Platforms

Integrate with Sales Tools

Send Server-Side Events

When to use the Events API

Send a server event

Read the visitor ID in the browser

Send it to your server with the action

Store it on the customer record

Send the event

Confirm it landed on the right person

Parameters that decide attribution

Name the event

Avoid duplicate events

Troubleshooting

​When to use the Events API

​Send a server event

Read the visitor ID in the browser

Send it to your server with the action

Store it on the customer record

Send the event

Confirm it landed on the right person

​Parameters that decide attribution

​Name the event

​Avoid duplicate events

​Troubleshooting

When to use the Events API

Send a server event

Parameters that decide attribution

Name the event

Avoid duplicate events

Troubleshooting