Skip to main content
L’Events API est l’équivalent côté serveur du Whop Pixel. POST /events 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é.
Avant de commencer, vous avez besoin de trois éléments :
  • Le Whop Pixel 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 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.
Read the visitor ID
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.
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.
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 :
5

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

Lister les événements 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.
cURL
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. L’événement apparaît également sur la page Événements 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. Le schéma complet de la requête figure sur la page de référence Créer un événement.

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. Tout autre event_name devient un événement personnalisé portant ce nom. Gardez des noms courts et stables, et réutilisez un ensemble restreint.
Custom event
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.