Conector de PostHog
Conecta PostHog con Brevo a través de Tajo para sincronizar datos de analíticas de producto, eventos de comportamiento de usuario y pertenencias a cohortes, con el fin de crear campañas de marketing basadas en datos y una interacción personalizada con los clientes.
Resumen
| Propiedad | Valor |
|---|---|
| Plataforma | PostHog |
| Categoría | Product Analytics (Personalizada) |
| Complejidad de configuración | Media |
| Integración oficial | No |
| Datos sincronizados | Eventos, Personas, Feature Flags, Cohortes |
| Método de autenticación | Personal API Key / Project Token |
Funcionalidades
- Sincronización de eventos - Reenvía los eventos de analítica de PostHog a Brevo para segmentación por comportamiento
- Sincronización de perfiles de personas - Sincroniza las propiedades de persona de PostHog con los atributos de contacto de Brevo
- Segmentación basada en cohortes - Asocia cohortes de PostHog con listas de contactos de Brevo
- Sincronización de feature flags - Segmenta contactos según los feature flags activados
- Datos de funnels - Usa los datos de funnels de conversión para una reactivación dirigida
- Metadatos de session replay - Enriquece contactos con métricas de interacción por sesión
Requisitos previos
Antes de empezar, asegúrate de tener:
- Una cuenta de PostHog (Cloud o self-hosted)
- Una Personal API Key desde PostHog Settings
- Tu Project API Key (token) desde Project Settings
- Una cuenta de Brevo con acceso a la API
- Una cuenta de Tajo con permisos de conector
Autenticación
Personal API Key (endpoints privados)
# Generate at https://app.posthog.com/settings/user-api-keysexport POSTHOG_PERSONAL_API_KEY=phx_your_personal_api_keyexport POSTHOG_PROJECT_TOKEN=phc_your_project_tokenexport POSTHOG_HOST=https://us.posthog.com # or https://eu.posthog.comexport TAJO_API_KEY=your_tajo_api_keyexport BREVO_API_KEY=your_brevo_api_key// Private API endpoints use Bearer authenticationconst headers = { 'Authorization': `Bearer ${process.env.POSTHOG_PERSONAL_API_KEY}`, 'Content-Type': 'application/json'};
// Public endpoints use the project tokenconst publicHeaders = { 'Content-Type': 'application/json'};// Token is passed in the request body for public endpointsSeguridad de la API Key
Las Personal API keys conceden acceso total a la cuenta. Nunca las expongas en código del lado del cliente. Usa la Project API Key (token) para endpoints públicos como la captura de eventos y la evaluación de feature flags.
Configuración
Configuración básica
connectors: posthog: enabled: true host: "${POSTHOG_HOST}" personal_api_key: "${POSTHOG_PERSONAL_API_KEY}" project_token: "${POSTHOG_PROJECT_TOKEN}" project_id: "12345"
sync: persons: true events: true cohorts: true feature_flags: true schedule: "0 */3 * * *" # Every 3 hours
event_filters: - "$pageview" - "purchase_completed" - "signup_completed" - "feature_used"
lists: all_users: 25 active_users: 26 power_users: 27Asignación de campos
field_mapping: email: email $name: FIRSTNAME $browser: BROWSER $os: OS $initial_referrer: REFERRAL_SOURCE total_events: EVENT_COUNT last_seen: LAST_ACTIVE_DATE signup_date: SIGNUP_DATE plan: SUBSCRIPTION_PLAN company: COMPANY cohort_names: POSTHOG_COHORTSEndpoints de la API
| Endpoint | Método | Descripción |
|---|---|---|
{host}/api/projects/{id}/persons/ | GET | Listar personas |
{host}/api/projects/{id}/events/ | GET | Listar eventos |
{host}/api/projects/{id}/cohorts/ | GET | Listar cohortes |
{host}/api/projects/{id}/feature_flags/ | GET | Listar feature flags |
{host}/api/projects/{id}/feature_flags/evaluation/ | POST | Evaluar flags |
{host}/api/projects/{id}/insights/ | GET | Listar insights guardados |
{host}/api/projects/{id}/query/ | POST | Ejecutar consultas HogQL |
{host}/i/v0/e | POST | Capturar eventos (público) |
{host}/decide/?v=3 | POST | Decisiones de feature flags (público) |
Ejemplos de código
Inicializar el conector
import { TajoClient } from '@tajo/sdk';
const tajo = new TajoClient({ apiKey: process.env.TAJO_API_KEY, brevoApiKey: process.env.BREVO_API_KEY});
await tajo.connectors.connect('posthog', { host: process.env.POSTHOG_HOST, personalApiKey: process.env.POSTHOG_PERSONAL_API_KEY, projectToken: process.env.POSTHOG_PROJECT_TOKEN, projectId: '12345'});Sincronizar personas con Brevo
// Paginate through PostHog personslet nextUrl = `${posthogHost}/api/projects/${projectId}/persons/?` + new URLSearchParams({ limit: '100' });
while (nextUrl) { const response = await fetch(nextUrl, { headers: { 'Authorization': `Bearer ${process.env.POSTHOG_PERSONAL_API_KEY}` } });
const data = await response.json();
for (const person of data.results) { const email = person.properties.$email || person.properties.email; if (!email) continue;
await tajo.contacts.sync({ email, attributes: { FIRSTNAME: person.properties.$name || person.properties.name, LAST_ACTIVE_DATE: person.properties.$last_seen, SIGNUP_DATE: person.created_at, EVENT_COUNT: person.properties.$event_count, BROWSER: person.properties.$browser, OS: person.properties.$os, REFERRAL_SOURCE: person.properties.$initial_referrer }, listIds: [25] }); }
nextUrl = data.next;}Sincronizar cohortes como listas de Brevo
// Get PostHog cohorts and sync members to Brevo listsconst cohortsResponse = await fetch( `${posthogHost}/api/projects/${projectId}/cohorts/`, { headers: { 'Authorization': `Bearer ${process.env.POSTHOG_PERSONAL_API_KEY}` } });
const { results: cohorts } = await cohortsResponse.json();
for (const cohort of cohorts) { // Get persons in this cohort const personsResponse = await fetch( `${posthogHost}/api/projects/${projectId}/cohorts/${cohort.id}/persons/`, { headers: { 'Authorization': `Bearer ${process.env.POSTHOG_PERSONAL_API_KEY}` } } );
const { results: persons } = await personsResponse.json();
for (const person of persons) { const email = person.properties.$email || person.properties.email; if (email) { await tajo.contacts.update(email, { attributes: { POSTHOG_COHORTS: cohort.name } }); } }}Ejecutar consultas HogQL para analítica
// Use HogQL to query analytics dataconst queryResponse = await fetch( `${posthogHost}/api/projects/${projectId}/query/`, { method: 'POST', headers: { 'Authorization': `Bearer ${process.env.POSTHOG_PERSONAL_API_KEY}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ query: { kind: 'HogQLQuery', query: ` SELECT properties.$email AS email, count() AS event_count, max(timestamp) AS last_event FROM events WHERE event = 'purchase_completed' AND timestamp > now() - interval 30 day GROUP BY email HAVING event_count > 3 ORDER BY event_count DESC LIMIT 1000 ` } }) });
const queryResult = await queryResponse.json();
for (const row of queryResult.results) { await tajo.contacts.update(row[0], { attributes: { PURCHASE_COUNT_30D: row[1], LAST_PURCHASE: row[2] } });}Límites de velocidad
| Categoría de endpoint | Límite | Notas |
|---|---|---|
| Endpoints de analítica | 240/min, 1.200/h | GET persons, events, insights |
| Endpoint de query | 2.400/h | HogQL y consultas personalizadas |
| Evaluación de feature flags | 600/min | Endpoint de evaluación local |
| Endpoints CRUD | 480/min, 4.800/h | Operaciones de crear, actualizar y eliminar |
| Endpoints públicos (capture) | Ilimitado | Captura de eventos, decisiones de flags |
Batch Exports
Para exportaciones masivas de datos de eventos, usa la funcionalidad de batch exports de PostHog en lugar de la API. Los batch exports admiten S3, BigQuery, Snowflake y otros destinos.
Resolución de problemas
| Problema | Causa | Solución |
|---|---|---|
| 401 Unauthorized | API key no válida | Verifica la Personal API Key en los ajustes |
| 400 Invalid project | Project ID incorrecto | Comprueba el project ID en la URL de PostHog |
| Lista de personas vacía | Sin usuarios identificados | Asegúrate de llamar a posthog.identify() |
| Propiedades que faltan | Propiedades no establecidas | Verifica las llamadas $set en el SDK de cliente |
| Rate limit 429 | Demasiadas peticiones | Aplica backoff y revisa las cabeceras de rate limit |
Modo depuración
connectors: posthog: debug: true log_level: verbose log_queries: true log_sync: trueBuenas prácticas
- Identifica a los usuarios - Llama siempre a
posthog.identify()con el email para habilitar la sincronización de personas - Usa cohortes para segmentar - Aprovecha las cohortes basadas en comportamiento de PostHog para crear listas de Brevo
- Agrupa las peticiones a la API - Usa paginación y procesamiento por lotes en grandes volúmenes de datos
- Usa HogQL para consultas complejas - Extrae analíticas personalizadas con consultas tipo SQL
- Configura batch exports - Para grandes volúmenes, prefiere los batch exports al polling de la API
- Filtra los eventos relevantes - Sincroniza solo los eventos relevantes para marketing y reduce ruido
Seguridad
- Personal API Key - Bearer token con alcance limitado
- Project token - Token público solo para operaciones del lado del cliente
- Solo HTTPS - Todos los endpoints requieren cifrado TLS
- IP allowlisting - Disponible para instancias self-hosted
- Scoping de claves - Crea API keys con scopes de permisos específicos
- GitHub secret scanning - PostHog colabora con GitHub para detectar claves filtradas