---
title: "Conector PostHog"
description: "Guia completo de integração do PostHog para sincronizar analytics de produto, feature flags e dados de comportamento do usuário com o Brevo através do Tajo."
url: https://tajo.io/pt/docs/connectors/custom/posthog/
markdown: https://tajo.io/pt/docs/connectors/custom/posthog.md
lang: pt-BR
robots: noindex
---

Solicite acesso antecipado

Indique o seu nome e endereço de e-mail profissional. Enviaremos um link para confirmar o seu pedido de acesso ao Tajo.

# Conector PostHog

Status do conector: Planejado Ainda não construído. O Tajo não executa este conector hoje.

| Campo de origem | Campo de destino | Valor de exemplo |
| --- | --- | --- |
| `record.id` | `source_id` | `record_1042` |
| `record.updated_at` | `updated_at` | `2026-10-18T08:00:00Z` |
| `record.value` | `value` | `sample_value` |

Conecte o PostHog ao Brevo através do Tajo para sincronizar dados de analytics de produto, eventos de comportamento do usuário e associações a cohorts para campanhas de marketing orientadas por dados e engajamento personalizado de clientes.

## Visão geral

| Propriedade | Valor |
| --- | --- |
| **Plataforma** | PostHog |
| **Categoria** | Product Analytics (Personalizado) |
| **Complexidade de configuração** | Média |
| **Integração oficial** | Não |
| **Dados sincronizados** | Eventos, Pessoas, Feature Flags, Cohorts |
| **Método de autenticação** | Personal API Key / Project Token |

## Recursos

- **Sincronização de eventos** - Encaminhe eventos de analytics do PostHog para o Brevo para segmentação comportamental
- **Sincronização de perfis de pessoas** - Sincronize propriedades de pessoas do PostHog para atributos de contato do Brevo
- **Segmentação baseada em cohorts** - Mapeie cohorts do PostHog para listas de contatos do Brevo
- **Sincronização de feature flags** - Segmente contatos por feature flags habilitadas
- **Dados de funil** - Use dados de funis de conversão para reengajamento direcionado
- **Metadados de session replay** - Enriqueça contatos com métricas de engajamento de sessão

## Pré-requisitos

Antes de começar, certifique-se de ter:

1. Uma conta PostHog (Cloud ou auto-hospedada)
2. Uma Personal API Key em [Configurações do PostHog](https://app.posthog.com/settings/user-api-keys)
3. Sua Project API Key (token) em [Configurações do Projeto](https://app.posthog.com/project/settings)
4. Uma conta Brevo com acesso à API
5. Uma conta Tajo com permissões de conector

## Autenticação

### Personal API Key (Endpoints privados)

```bash
# 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
```

```javascript
// 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
```

Segurança da API Key

Personal API keys fornecem acesso completo à conta. Nunca as exponha em código do lado do cliente. Use a Project API Key (token) para endpoints públicos como captura de eventos e avaliação de feature flags.

## Configuração

### Configuração básica

```yaml
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
```

### Mapeamento de campos

```yaml
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 da API

| Endpoint | Método | Descrição |
| --- | --- | --- |
| `{host}/api/projects/{id}/persons/` | GET | Listar pessoas |
| `{host}/api/projects/{id}/events/` | GET | Listar eventos |
| `{host}/api/projects/{id}/cohorts/` | GET | Listar cohorts |
| `{host}/api/projects/{id}/feature_flags/` | GET | Listar feature flags |
| `{host}/api/projects/{id}/feature_flags/evaluation/` | POST | Avaliar flags |
| `{host}/api/projects/{id}/insights/` | GET | Listar insights salvos |
| `{host}/api/projects/{id}/query/` | POST | Executar consultas HogQL |
| `{host}/i/v0/e` | POST | Capturar eventos (público) |
| `{host}/decide/?v=3` | POST | Decisões de feature flag (público) |

## Exemplos de código

### Inicializar o conector

```javascript
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 pessoas para o Brevo

```javascript
// 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 cohorts como listas do Brevo

```javascript
// 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
        }
      });
    }
  }
}
```

### Executar consultas HogQL para analytics

```javascript
// 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]
    }
  });
}
```

## Limites de taxa

| Categoria de Endpoint | Limite | Observações |
| --- | --- | --- |
| Endpoints de analytics | 240/min, 1.200/hora | GET pessoas, eventos, insights |
| Endpoint de query | 2.400/hora | Consultas HogQL e customizadas |
| Avaliação de feature flag | 600/min | Endpoint de avaliação local |
| Endpoints CRUD | 480/min, 4.800/hora | Operações de criação, atualização, exclusão |
| Endpoints públicos (capture) | Ilimitado | Captura de eventos, decisões de flag |

Batch Exports

Para exportações de dados de eventos em grande escala, use o recurso de batch exports do PostHog em vez da API. Os batch exports suportam S3, BigQuery, Snowflake e outros destinos.

## Solução de problemas

| Problema | Causa | Solução |
| --- | --- | --- |
| 401 Unauthorized | API key inválida | Verifique a Personal API Key nas configurações |
| 400 Invalid project | ID de projeto errado | Verifique o ID do projeto na URL do PostHog |
| Lista de pessoas vazia | Nenhum usuário identificado | Certifique-se de que `posthog.identify()` é chamado |
| Propriedades ausentes | Propriedades não definidas | Verifique as chamadas `$set` no SDK do cliente |
| Limite de taxa 429 | Muitas requisições | Implemente backoff, verifique cabeçalhos de limite de taxa |

### Modo de depuração

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

## Melhores práticas

1. **Identifique usuários** - Sempre chame `posthog.identify()` com e-mail para habilitar a sincronização de pessoas
2. **Use cohorts para segmentação** - Aproveite os cohorts comportamentais do PostHog para listas do Brevo
3. **Agrupe requisições à API em lotes** - Use paginação e processamento em lote para grandes conjuntos de dados
4. **Use HogQL para consultas complexas** - Extraia analytics customizadas com consultas similares a SQL
5. **Configure batch exports** - Para grandes volumes de dados, prefira batch exports em vez de polling à API
6. **Filtre eventos relevantes** - Sincronize apenas eventos relevantes para marketing para reduzir ruído

## Segurança

- **Personal API Key** - Autenticação Bearer token com escopo definido
- **Project token** - Token público apenas para operações do lado do cliente
- **Somente HTTPS** - Todos os endpoints requerem criptografia TLS
- **IP allowlisting** - Disponível para instâncias auto-hospedadas
- **Escopo de chaves** - Crie API keys com escopos específicos de permissão
- **GitHub secret scanning** - O PostHog tem parceria com o GitHub para detecção de chaves vazadas

## Recursos relacionados

- [Conector Optimizely](https://tajo.io/pt/docs/connectors/custom/optimizely)
- [Conector Segment](https://tajo.io/pt/docs/connectors/custom/segment)
- [Conector Snowflake](https://tajo.io/pt/docs/connectors/custom/snowflake)
- [Documentação da API PostHog](https://posthog.com/docs/api)