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 parbiz_.
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 appelwhop.track peut se déclencher là où l’action se produit, utilisez-le plutôt.
Envoyer un événement serveur
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.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.
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 :Vérifier qu'il a été associé à la bonne personne
Lister les événements accepte un ID de visiteur comme Votre événement serveur apparaît à côté des pages vues du pixel avec le même
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
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
Seulsaccount_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. Unlead 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
É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êmeevent_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 deuser.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.
