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

PropiedadValor
PlataformaPostHog
CategoríaProduct Analytics (Personalizada)
Complejidad de configuraciónMedia
Integración oficialNo
Datos sincronizadosEventos, Personas, Feature Flags, Cohortes
Método de autenticaciónPersonal 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:

  1. Una cuenta de PostHog (Cloud o self-hosted)
  2. Una Personal API Key desde PostHog Settings
  3. Tu Project API Key (token) desde Project Settings
  4. Una cuenta de Brevo con acceso a la API
  5. Una cuenta de Tajo con permisos de conector

Autenticación

Personal API Key (endpoints privados)

Terminal window
# Generate at https://app.posthog.com/settings/user-api-keys
export POSTHOG_PERSONAL_API_KEY=phx_your_personal_api_key
export POSTHOG_PROJECT_TOKEN=phc_your_project_token
export POSTHOG_HOST=https://us.posthog.com # or https://eu.posthog.com
export TAJO_API_KEY=your_tajo_api_key
export BREVO_API_KEY=your_brevo_api_key
// Private API endpoints use Bearer authentication
const headers = {
'Authorization': `Bearer ${process.env.POSTHOG_PERSONAL_API_KEY}`,
'Content-Type': 'application/json'
};
// Public endpoints use the project token
const publicHeaders = {
'Content-Type': 'application/json'
};
// Token is passed in the request body for public endpoints

Seguridad 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: 27

Asignació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_COHORTS

Endpoints de la API

EndpointMétodoDescripción
{host}/api/projects/{id}/persons/GETListar personas
{host}/api/projects/{id}/events/GETListar eventos
{host}/api/projects/{id}/cohorts/GETListar cohortes
{host}/api/projects/{id}/feature_flags/GETListar feature flags
{host}/api/projects/{id}/feature_flags/evaluation/POSTEvaluar flags
{host}/api/projects/{id}/insights/GETListar insights guardados
{host}/api/projects/{id}/query/POSTEjecutar consultas HogQL
{host}/i/v0/ePOSTCapturar eventos (público)
{host}/decide/?v=3POSTDecisiones 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 persons
let 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 lists
const 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 data
const 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 endpointLímiteNotas
Endpoints de analítica240/min, 1.200/hGET persons, events, insights
Endpoint de query2.400/hHogQL y consultas personalizadas
Evaluación de feature flags600/minEndpoint de evaluación local
Endpoints CRUD480/min, 4.800/hOperaciones de crear, actualizar y eliminar
Endpoints públicos (capture)IlimitadoCaptura 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

ProblemaCausaSolución
401 UnauthorizedAPI key no válidaVerifica la Personal API Key en los ajustes
400 Invalid projectProject ID incorrectoComprueba el project ID en la URL de PostHog
Lista de personas vacíaSin usuarios identificadosAsegúrate de llamar a posthog.identify()
Propiedades que faltanPropiedades no establecidasVerifica las llamadas $set en el SDK de cliente
Rate limit 429Demasiadas peticionesAplica backoff y revisa las cabeceras de rate limit

Modo depuración

connectors:
posthog:
debug: true
log_level: verbose
log_queries: true
log_sync: true

Buenas prácticas

  1. Identifica a los usuarios - Llama siempre a posthog.identify() con el email para habilitar la sincronización de personas
  2. Usa cohortes para segmentar - Aprovecha las cohortes basadas en comportamiento de PostHog para crear listas de Brevo
  3. Agrupa las peticiones a la API - Usa paginación y procesamiento por lotes en grandes volúmenes de datos
  4. Usa HogQL para consultas complejas - Extrae analíticas personalizadas con consultas tipo SQL
  5. Configura batch exports - Para grandes volúmenes, prefiere los batch exports al polling de la API
  6. 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

Recursos relacionados

Subscribe to updates

developer-docs

Drop your email or phone number — we'll send you what matters next.

auto-detect
Asistente AI

¡Hola! Pregúntame lo que quieras sobre la documentación.