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

# Envoyer des événements côté serveur

> Envoyez des événements de conversion depuis votre serveur et associez-les au visiteur déjà suivi par le Whop Pixel.

L'Events API est l'équivalent côté serveur du [Whop Pixel](https://docs.whop.com/fr/developer/ads/pixel.md). [`POST /events`](https://docs.whop.com/fr/api-reference/events/create-event) accepte les mêmes événements que ceux envoyés par le pixel depuis le navigateur, ce qui vous permet de déclarer des conversions qui se produisent là où aucun pixel ne s'exécute. Cela couvre une vente conclue dans votre CRM, un paiement sur votre propre backend, un webhook provenant d'un outil de formulaire ou de réservation, ou un appel qu'un commercial marque comme réservé.

> [!NOTE]
>
> **Avant de commencer**, vous avez besoin de trois éléments :
>
> * Le [Whop Pixel](https://docs.whop.com/fr/developer/ads/pixel.md) installé sur chaque page de votre tunnel. Il crée l'ID de visiteur que ce guide transmet.
> * Une clé API avec la permission `event:create`. [Créez-en une](https://whop.com/dashboard/developer) sous **Account API Keys**, et conservez-la sur votre serveur. Ne la placez jamais dans du code exécuté dans le navigateur.
> * L'ID de votre compte, la partie de l'URL de votre tableau de bord située après `dashboard/` et qui commence par `biz_`.

## Quand utiliser l'Events API

La plupart des intégrations n'en ont pas besoin. Le pixel déclare déjà tout ce qui se passe dans le navigateur, et renseigne lui-même l'ID du visiteur, l'adresse IP et le user agent. Utilisez l'Events API uniquement lorsque votre serveur est le seul endroit à savoir qu'une conversion a eu lieu. Si un appel `whop.track` peut se déclencher là où l'action se produit, utilisez-le plutôt.

## Envoyer un événement serveur

### 1. Lire l'ID du visiteur dans le navigateur

Le pixel stocke l'ID de chaque visiteur dans un cookie first-party nommé `_wuid` sur votre domaine, et le réplique dans `localStorage` sous la même clé. La valeur ressemble à `wuid_k3j9x2m1p8q4r7s0t5u6`. Lisez-la au moment où le visiteur effectue l'action que vous déclarerez plus tard, et non au chargement de la page. Le cookie n'existe qu'une fois que le snippet du pixel s'est exécuté sur la page.

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

Chaque sous-domaine reçoit son propre `_wuid`. Le pixel les relie à une même personne ; lisez donc le cookie présent sur la page où a lieu la transmission.

### 2. L'envoyer à votre serveur avec l'action

Joignez l'ID du visiteur à la requête qui transmet déjà l'action à votre backend : un envoi de formulaire, un appel de checkout, une requête d'inscription. Capturez en même temps l'URL de la page. Elle contient les UTM et les identifiants de clic que votre serveur ne peut pas voir autrement.

```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 votre backend répond sur le même hôte que la page, le cookie `_wuid` arrive de lui-même avec la requête. Lisez-le à cet endroit au lieu de l'envoyer depuis le navigateur. Le cookie est défini pour cet hôte uniquement ; une requête de `example.com` vers `api.example.com` ne le transporte donc pas.

Votre serveur voit déjà l'adresse IP et le user agent du visiteur dans cette requête. Conservez-les tous les deux.

### 3. Le stocker sur la fiche client

Enregistrez l'ID du visiteur, l'URL de la page, l'adresse IP et le user agent sur le lead, le client ou la commande. La conversion que vous déclarez peut survenir plusieurs jours après la visite. Une affaire conclue par votre équipe commerciale la semaine prochaine a toujours besoin de l'ID du visiteur de la visite d'origine pour être attribuée. Whop accepte les événements datant de 28 jours maximum.

### 4. Envoyer l'événement

Publiez l'événement depuis votre serveur avec votre clé API. L'exemple déclare un lead provenant d'un visiteur arrivé depuis une publicité, qui a rempli un formulaire de devis puis a été qualifié dans 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",
    },
)
```

L'`url` de l'exemple est la page sur laquelle arrive un visiteur après avoir touché une publicité Whop sur Meta. `utm_meta_ad_id`, `utm_meta_adset_id` et `utm_meta_campaign_id` sont les ID du réseau. `wacid`, `wasid` et `waid` sont les ID Whop de la campagne, du groupe d'annonces et de la publicité. `utm_source` désigne la surface (`fb`, `ig`, `msg` ou `an`), `utm_placement` l'emplacement, `utm_content` et `utm_adset` les noms de la publicité et du groupe d'annonces, et `fbclid` est le marqueur que le réseau ajoute lui-même. Whop détermine à partir de ces éléments quelle publicité a généré la visite ; stockez donc l'URL entière plutôt que d'en extraire des paramètres.

La réponse renvoie l'ID de l'événement stocké. Whop préfixe votre `event_id` avec le compte afin que les ID de comptes différents n'entrent jamais en conflit :

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

### 5. Vérifier qu'il a été associé à la bonne personne

[Lister les événements](https://docs.whop.com/fr/api-reference/events/list-events.md) accepte un ID de visiteur comme `identifier`, ce qui vous permet de consulter l'ensemble du parcours auquel l'événement a été rattaché. La requête nécessite une clé disposant d'une permission de lecture telle que `company:basic:read`.

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

Votre événement serveur apparaît à côté des pages vues du pixel avec le même `person_id`. Si les pages vues sont présentes mais pas votre événement, l'ID du visiteur ne correspondait pas. Consultez [Dépannage](#troubleshooting). L'événement apparaît également sur la [page Événements](https://whop.com/dashboard/events) de votre tableau de bord.

## Paramètres qui déterminent l'attribution

Seuls `account_id` et `event_name` sont obligatoires. Le reste du payload est ce qui rend l'événement attribuable ; considérez donc ces champs comme obligatoires également.

| Champ | Ce qu'il faut envoyer |
| - | - |
| `user.anonymous_id` | L'ID du visiteur provenant du cookie `_wuid`. C'est le seul champ qui relie un événement serveur à la session du navigateur issue de la publicité. Sans lui, Whop ne peut effectuer la correspondance que sur l'e-mail ou le téléphone. |
| `user.email`, `user.phone` | En texte brut, exactement tels que le client les a saisis. Whop effectue la correspondance sur ces champs lorsque le pixel les a capturés auparavant. Un e-mail haché est ignoré car considéré comme invalide. |
| `user.first_name`, `user.last_name`, `user.external_id` | Toute autre information dont vous disposez. `external_id` est votre propre ID client. |
| `event_id` | Un ID stable pour cette action précise : votre numéro de commande, l'ID de l'affaire ou l'ID de soumission du formulaire. Whop stocke chaque paire `event_name` et `event_id` une seule fois ; une nouvelle tentative ou une seconde copie de la même conversion est donc fusionnée en un seul événement. Consultez [Éviter les événements en double](#avoid-duplicate-events). |
| `event_time` | Le moment où l'action s'est produite, sous forme d'horodatage ISO 8601. Par défaut, l'heure actuelle. Whop rejette tout ce qui date de plus de 28 jours et ramène les horodatages futurs à l'heure actuelle. Envoyez l'heure réelle, et non l'heure d'exécution de votre tâche. |
| `value`, `currency` | La valeur monétaire et son code ISO 4217 en minuscules, tel que `usd`. Facultatif pour la plupart des événements. Obligatoire et supérieur à zéro pour `purchase`. |
| `url` | La page sur laquelle se trouvait le visiteur au début de l'action, query string comprise. Lors d'une visite issue d'une publicité Whop, cette query string contient les ID à partir desquels Whop détermine la campagne, le groupe d'annonces et la publicité. |
| `context.ip_address`, `context.user_agent` | Ceux du visiteur, copiés depuis sa requête de navigateur d'origine. Whop les lit depuis la connexion uniquement pour les appels non authentifiés provenant du navigateur. Un appel serveur ne bénéficie d'aucune déduction ; un événement sans ces champs n'a donc aucun signal d'appareil ni de localisation. |
| `context.fbclid`, `context.gclid`, `context.ttclid`, `context.utm_*` | Les ID des réseaux publicitaires et les paramètres `utm_*` de l'URL de la page de destination, si vous les avez stockés. |
| `context.fbp`, `context.fbc` | Les valeurs des cookies Meta `_fbp` et `_fbc` du navigateur du visiteur, si vous les avez capturées. |
| `action_source` | L'endroit où l'action s'est produite : `website`, `app`, `email`, `phone_call`, `chat`, `physical_store`, `system_generated`, `business_messaging` ou `other`. |

Le schéma complet de la requête figure sur la page de référence [Créer un événement](https://docs.whop.com/fr/api-reference/events/create-event.md).

## Nommer l'événement

Utilisez les mêmes noms que le pixel. Un `lead` que vous déclarez depuis votre serveur est enregistré comme le même événement qu'un `lead` déclaré par le pixel ; il est donc comptabilisé dans les résultats d'une campagne évaluée sur les leads.

| Événement | Quand l'envoyer |
| - | - |
| `lead` | Un visiteur soumet ses coordonnées ou un formulaire d'inscription |
| `schedule` | Un visiteur réserve un appel ou un rendez-vous |
| `submit_application` | Un visiteur soumet une candidature |
| `contact` | Un visiteur entame une conversation ou une demande de contact |
| `complete_registration` | Une inscription ou un enregistrement est finalisé |
| `view_content` | Un visiteur consulte une page ou un contenu clé |
| `add_to_cart` | Un visiteur ajoute un article à un panier |
| `initiate_checkout` | Un visiteur atteint le checkout |
| `purchase` | Une vente est finalisée sur votre propre checkout. `value` est obligatoire |

Tout autre `event_name` devient un événement personnalisé portant ce nom. Gardez des noms courts et stables, et réutilisez un ensemble restreint.

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

> [!WARNING]
>
> N'envoyez jamais `purchase` pour une vente traitée par Whop. Whop enregistre automatiquement chaque checkout, achat, abonnement et essai effectué sur son propre checkout et le déclare au réseau publicitaire. N'envoyez que les événements que Whop ne peut pas voir.

## Éviter les événements en double

Si la même conversion peut parvenir à Whop à la fois depuis le navigateur et depuis votre serveur, envoyez-la depuis les deux avec le même `event_name` et le même `event_id`. Whop en conserve une seule copie. C'est la configuration la plus sûre lorsqu'un formulaire déclenche `whop.track("lead", { event_id })` à la soumission et que votre backend déclare à nouveau le même lead après l'avoir validé.

L'`event_id` identifie une action, et non un type d'action. Chaque lead a besoin du sien. Une valeur inventée au moment de l'envoi est nouvelle à chaque fois et n'empêche donc rien. Utilisez un ID dont votre système dispose déjà pour cette action précise.

## Dépannage

**L'événement est stocké mais n'est attribué à aucune publicité.** L'événement ne contenait pas de `user.anonymous_id`, ou contenait une valeur que le pixel n'a jamais utilisée. Les causes habituelles sont la lecture du cookie avant l'exécution du snippet du pixel, sa lecture sur un domaine sans pixel, ou le stockage de l'ID du visiteur sur la mauvaise fiche. Confirmez la correction en listant les événements pour cet ID de visiteur. Les pages vues du pixel doivent apparaître sous le même `identifier` que votre événement.

**`400` avec un message concernant `event_time`.** L'horodatage date de plus de 28 jours. Envoyez l'événement plus près du moment où il se produit, ou abandonnez-le.

**`400` sur un événement `purchase`.** `value` est absent ou n'est pas supérieur à zéro. Les réseaux publicitaires ne peuvent pas optimiser vers une vente sans montant ; Whop la rejette donc.

**`401` ou `403`.** La clé est absente, ne dispose pas de `event:create`, ou appartient à un compte différent de `account_id`. Les clés de production utilisent `https://api.whop.com/api/v1`.


## Related topics

- [Accepter des paiements ponctuels](https://docs.whop.com/fr/developer/guides/ios/accept-one-time-payments.md)
- [Suivre les visiteurs](https://docs.whop.com/fr/developer/websites/tracking.md)
- [API Chat](https://docs.whop.com/fr/developer/guides/chat.md)
