POST /events 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.
Antes de empezar, necesitas tres cosas:
- El Whop Pixel 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 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 porbiz_.
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 awhop.track puede dispararse donde ocurre la acción, usa eso en su lugar.
Enviar un evento de servidor
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.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.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.
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.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:Confirma que llegó a la persona correcta
Listar Events acepta un ID de visitante como Tu evento de servidor aparece junto a las visitas a páginas del píxel con el mismo
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.cURL
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. El evento también aparece en la página Events de tu panel.Parámetros que deciden la atribución
Soloaccount_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.
El esquema completo de la solicitud está en la página de referencia Crear Event.
Nombrar el evento
Usa los mismos nombres que el píxel. Unlead 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.
Cualquier otro
event_name se convierte en un evento personalizado con ese nombre. Usa nombres cortos y estables, y reutiliza un conjunto reducido.
Custom event
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 mismoevent_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 llevabauser.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.
