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

# Enviar eventos del lado del servidor

> Envía eventos de conversión desde tu servidor y vincúlalos al visitante que el Whop Pixel ya rastrea.

La Events API es el equivalente del lado del servidor del [Whop Pixel](https://docs.whop.com/es/developer/ads/pixel.md). [`POST /events`](https://docs.whop.com/es/api-reference/events/create-event) acepta los mismos eventos que el píxel envía desde el navegador, así que puedes informar de conversiones que ocurren donde no se ejecuta ningún píxel. Eso incluye una venta cerrada en tu CRM, un pago en tu propio backend, un webhook de una herramienta de formularios o de reservas, o una llamada que un comercial marca como reservada.

> [!NOTE]
>
> **Antes de empezar**, necesitas tres cosas:
>
> * El [Whop Pixel](https://docs.whop.com/es/developer/ads/pixel.md) instalado en todas las páginas de tu embudo. Crea el ID de visitante que esta guía va transmitiendo.
> * Una API key con el permiso `event:create`. [Crea una](https://whop.com/dashboard/developer) en **Account API Keys** y guárdala en tu servidor. Nunca la pongas en código del navegador.
> * El ID de tu cuenta, la parte de la URL de tu panel que va después de `dashboard/` y empieza por `biz_`.

## Cuándo usar la Events API

La mayoría de las integraciones no lo necesitan. El píxel ya informa de todo lo que ocurre en el navegador y rellena por sí solo el ID de visitante, la dirección IP y el user agent. Usa la Events API solo cuando tu servidor sea el único lugar que sabe que se produjo una conversión. Si una llamada a `whop.track` puede dispararse donde ocurre la acción, usa eso en su lugar.

## Enviar un evento de servidor

### 1. Lee el ID de visitante en el navegador

El píxel guarda el ID de cada visitante en una cookie propia llamada `_wuid` en tu dominio, y lo replica en `localStorage` con la misma clave. El valor tiene el aspecto `wuid_k3j9x2m1p8q4r7s0t5u6`. Léelo en el momento en que el visitante realiza la acción de la que informarás después, no al cargar la página. La cookie solo existe después de que el snippet del píxel se haya ejecutado en la página.

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

Cada subdominio tiene su propia `_wuid`. El píxel las vincula a una sola persona, así que lee la cookie que esté en la página donde se produce el traspaso.

### 2. Envíalo a tu servidor con la acción

Adjunta el ID de visitante a la solicitud que ya lleva la acción a tu backend: el envío de un formulario, una llamada de checkout, una solicitud de registro. Captura la URL de la página al mismo tiempo. Contiene los UTM y los IDs de clic que tu servidor no puede ver de otro modo.

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

Si tu backend responde en el mismo host que la página, la cookie `_wuid` llega sola con la solicitud. Léela ahí en lugar de enviarla desde el navegador. La cookie solo está establecida para ese host, así que una solicitud de `example.com` a `api.example.com` no la lleva.

Tu servidor ya ve la dirección IP y el user agent del visitante en esa solicitud. Guarda ambos.

### 3. Guárdalo en el registro del cliente

Guarda el ID de visitante, la URL de la página, la dirección IP y el user agent en el lead, el cliente o el pedido. La conversión de la que informes puede producirse días después de la visita. Un acuerdo que tu equipo de ventas cierre la semana que viene sigue necesitando el ID de visitante de la visita original para poder atribuirse. Whop acepta eventos de hasta 28 días de antigüedad.

### 4. Envía el evento

Publica el evento desde tu servidor con tu API key. El ejemplo informa de un lead de un visitante que llegó desde un anuncio, rellenó un formulario de presupuesto y luego fue calificado en un 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",
    },
)
```

La `url` del ejemplo es la página a la que llega un visitante después de tocar un anuncio de Whop en Meta. `utm_meta_ad_id`, `utm_meta_adset_id` y `utm_meta_campaign_id` son los IDs de la red. `wacid`, `wasid` y `waid` son los IDs de la campaña, el grupo de anuncios y el anuncio de Whop. `utm_source` indica la superficie (`fb`, `ig`, `msg` o `an`), `utm_placement` la ubicación, `utm_content` y `utm_adset` los nombres del anuncio y del grupo de anuncios, y `fbclid` es la etiqueta que añade la propia red. Whop determina a partir de ellos qué anuncio generó la visita, así que guarda la URL completa en lugar de extraer parámetros de ella.

La respuesta devuelve el ID del evento guardado. Whop antepone la cuenta a tu `event_id` para que los IDs de cuentas distintas nunca coincidan:

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

### 5. Confirma que llegó a la persona correcta

[Listar Events](https://docs.whop.com/es/api-reference/events/list-events.md) acepta un ID de visitante como `identifier`, así que puedes leer todo el recorrido al que se unió el evento. La solicitud necesita una key con un permiso de lectura como `company:basic:read`.

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

Tu evento de servidor aparece junto a las visitas a páginas del píxel con el mismo `person_id`. Si las visitas a páginas están pero tu evento no, el ID de visitante no coincidió. Consulta [Solución de problemas](#troubleshooting). El evento también aparece en la [página Events](https://whop.com/dashboard/events) de tu panel.

## Parámetros que deciden la atribución

Solo `account_id` y `event_name` son obligatorios. El resto del payload es lo que hace que el evento sea atribuible, así que trata estos campos también como obligatorios.

| Campo | Qué enviar |
| - | - |
| `user.anonymous_id` | El ID de visitante de la cookie `_wuid`. Es el único campo que vincula un evento de servidor con la sesión del navegador que vino del anuncio. Sin él, Whop solo puede hacer coincidir por correo electrónico o teléfono. |
| `user.email`, `user.phone` | Texto sin formato, exactamente como los introdujo el cliente. Whop hace coincidir con ellos cuando el píxel los capturó antes. Un correo electrónico con hash se descarta por no válido. |
| `user.first_name`, `user.last_name`, `user.external_id` | Cualquier otra cosa que sepas. `external_id` es tu propio ID de cliente. |
| `event_id` | Un ID estable para esta acción concreta: tu número de pedido, ID de acuerdo o ID de envío de formulario. Whop guarda cada par de `event_name` y `event_id` una sola vez, así que un reintento o una segunda copia de la misma conversión se agrupa en un solo evento. Consulta [Evitar eventos duplicados](#avoid-duplicate-events). |
| `event_time` | Cuándo ocurrió la acción, como marca de tiempo ISO 8601. Por defecto, ahora. Whop rechaza todo lo que tenga más de 28 días y limita las marcas de tiempo futuras a la hora actual. Envía la hora real, no la hora en que se ejecutó tu tarea. |
| `value`, `currency` | El valor monetario y su código ISO 4217 en minúsculas, como `usd`. Opcional en la mayoría de los eventos. Obligatorio y mayor que cero en `purchase`. |
| `url` | La página en la que estaba el visitante cuando empezó la acción, incluida su query string. En una visita desde un anuncio de Whop, esa query string contiene los IDs a partir de los cuales Whop determina la campaña, el grupo de anuncios y el anuncio. |
| `context.ip_address`, `context.user_agent` | Los del visitante, copiados de su solicitud original del navegador. Whop los lee de la conexión solo en las llamadas del navegador no autenticadas. En una llamada de servidor no se deduce nada, así que un evento sin ellos no tiene señales de dispositivo ni de ubicación. |
| `context.fbclid`, `context.gclid`, `context.ttclid`, `context.utm_*` | Los IDs de la red publicitaria y los parámetros `utm_*` de la URL de la página de destino, si los guardaste. |
| `context.fbp`, `context.fbc` | Los valores de las cookies `_fbp` y `_fbc` de Meta del navegador del visitante, si los capturaste. |
| `action_source` | Dónde ocurrió la acción: `website`, `app`, `email`, `phone_call`, `chat`, `physical_store`, `system_generated`, `business_messaging` u `other`. |

El esquema completo de la solicitud está en la página de referencia [Crear Event](https://docs.whop.com/es/api-reference/events/create-event.md).

## Nombrar el evento

Usa los mismos nombres que el píxel. Un `lead` del que informas desde tu servidor se registra como el mismo evento que un `lead` del que informa el píxel, así que cuenta para los resultados de una campaña que se evalúa por leads.

| Evento | Cuándo enviarlo |
| - | - |
| `lead` | Un visitante envía sus datos de contacto o un formulario de suscripción |
| `schedule` | Un visitante reserva una llamada o una cita |
| `submit_application` | Un visitante envía una solicitud |
| `contact` | Un visitante inicia una conversación o una solicitud de contacto |
| `complete_registration` | Se completa un alta o un registro |
| `view_content` | Un visitante ve una página o un contenido clave |
| `add_to_cart` | Un visitante añade un artículo a un carrito |
| `initiate_checkout` | Un visitante llega al checkout |
| `purchase` | Se completa una venta en tu propio checkout. `value` es obligatorio |

Cualquier otro `event_name` se convierte en un evento personalizado con ese nombre. Usa nombres cortos y estables, y reutiliza un conjunto reducido.

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

> [!WARNING]
>
> Nunca envíes `purchase` para una venta que procesó Whop. Whop registra automáticamente cada checkout, compra, suscripción y prueba en su propio checkout y lo comunica a la red publicitaria. Envía solo los eventos que Whop no puede ver.

## Evitar eventos duplicados

Si la misma conversión puede llegar a Whop tanto desde el navegador como desde tu servidor, envíala desde ambos con el mismo `event_name` y el mismo `event_id`. Whop conserva una copia. Esta es la configuración más segura cuando un formulario dispara `whop.track("lead", { event_id })` al enviarse y tu backend vuelve a informar del mismo lead después de validarlo.

El `event_id` identifica una acción concreta, no el tipo de acción. Cada lead necesita el suyo. Un valor inventado en el momento del envío es nuevo cada vez, así que no evita nada. Usa un ID que tu sistema ya tenga para esa acción concreta.

## Solución de problemas

**El evento se guarda pero no se atribuye a un anuncio.** El evento no llevaba `user.anonymous_id`, o llevaba un valor que el píxel nunca usó. Las causas habituales son leer la cookie antes de que se ejecutara el snippet del píxel, leerla en un dominio sin el píxel o guardar el ID de visitante en el registro equivocado. Confirma la corrección listando los eventos de ese ID de visitante. Las visitas a páginas del píxel deben aparecer con el mismo `identifier` que tu evento.

**`400` con un mensaje sobre `event_time`.** La marca de tiempo tiene más de 28 días. Envía el evento más cerca del momento en que ocurre, o descártalo.

**`400` en un evento `purchase`.** Falta `value` o no es mayor que cero. Las redes publicitarias no pueden optimizar hacia una venta sin importe, así que Whop la rechaza.

**`401` o `403`.** Falta la key, no tiene `event:create` o pertenece a una cuenta distinta de `account_id`. Las keys de producción usan `https://api.whop.com/api/v1`.


## Related topics

- [Acepta pagos únicos](https://docs.whop.com/es/developer/guides/ios/accept-one-time-payments.md)
- [Alojamiento de sitios web en Whop](https://docs.whop.com/es/developer/websites/hosting.md)
- [PixelSetupElement](https://docs.whop.com/es/elements/latest/websites/pixel-setup.md)
