Connectors

Connectors let you pipe events from your existing analytics stack into Retivo without changing your tracking code. Each connector normalizes vendor-specific payloads into Retivo's canonical event format.

Supported Platforms

All connector endpoints require API key authentication:

Authorization: Bearer rt_live_...

Segment

Point a Segment webhook destination at your Retivo connector endpoint.

Identify

{
  "type": "identify",
  "userId": "user-123",
  "traits": {
    "name": "Jane Smith",
    "email": "jane@example.com",
    "plan": "pro",
    "company": { "name": "Acme Inc" }
  },
  "timestamp": "2026-04-04T12:00:00Z"
}

Creates or updates the user in Retivo with the provided traits.

Track

{
  "type": "track",
  "userId": "user-123",
  "event": "Project Created",
  "properties": {
    "projectName": "Q1 Roadmap",
    "templateUsed": true
  },
  "timestamp": "2026-04-04T12:00:00Z"
}

Page

{
  "type": "page",
  "userId": "user-123",
  "name": "Dashboard",
  "properties": {
    "url": "https://app.example.com/dashboard"
  }
}

Page calls are normalized to a page_viewed event with the page name in properties.

PostHog

Configure a PostHog webhook to forward events to Retivo.

Event Format

{
  "event": "project_created",
  "distinct_id": "user-123",
  "properties": {
    "projectName": "Q1 Roadmap",
    "$current_url": "https://app.example.com/projects"
  },
  "timestamp": "2026-04-04T12:00:00.000Z"
}

Mapping rules:

• distinct_id maps to Retivo user_id
• $pageview events are normalized to page_viewed
• Internal PostHog events (starting with $, except $pageview and $identify) are skipped
• $set and $set_once properties are extracted as user traits

Identify

{
  "event": "$identify",
  "distinct_id": "user-123",
  "properties": {
    "$set": {
      "name": "Jane Smith",
      "email": "jane@example.com"
    }
  }
}

Mixpanel

Forward Mixpanel events via webhook or server-side export.

Event Format

{
  "event": "Project Created",
  "properties": {
    "distinct_id": "user-123",
    "time": 1743782400,
    "projectName": "Q1 Roadmap",
    "$city": "San Francisco"
  }
}

Mapping rules:

• properties.distinct_id maps to Retivo user_id
• properties.time (Unix seconds) is converted to an ISO timestamp
• Internal Mixpanel properties ($city, $region, $browser, etc.) are preserved in event properties

Response Format

All connector endpoints return a standard response:

{
  "accepted": 2,
  "users_upserted": 1
}

If the payload can't be normalized (e.g., missing user_id), the connector returns a 400 error:

{ "error": "Missing user_id / distinct_id" }

Setup Guides

Segment Webhook Destination

1. In Segment, go to Connections > Destinations > Add Destination
2. Select Webhooks (Actions)
3. Set the URL to https://retivo.ai/api/connectors/segment
4. Add a header: Authorization: Bearer rt_live_...
5. Map the events you want to forward

PostHog Webhook

1. In PostHog, go to Data Pipeline > Destinations
2. Add a new webhook destination
3. Set the URL to https://retivo.ai/api/connectors/posthog
4. Add the Authorization header with your API key
5. Select which events to forward

Mixpanel Webhook

1. In Mixpanel, go to Settings > Integrations > Webhooks
2. Add a new webhook with URL https://retivo.ai/api/connectors/mixpanel
3. Include the Authorization: Bearer rt_live_... header
4. Choose the events to export

Testing Your Connector

Use rt_test_ prefixed API keys to verify event normalization without triggering real interventions. Events ingested with test keys appear in your dashboard tagged as test data.

Segment

curl -X POST https://retivo.ai/api/connectors/segment \
  -H "Authorization: Bearer rt_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "track",
    "userId": "test-user-1",
    "event": "test_event",
    "properties": { "source": "manual_test" },
    "timestamp": "2026-04-04T12:00:00Z"
  }'

PostHog

curl -X POST https://retivo.ai/api/connectors/posthog \
  -H "Authorization: Bearer rt_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "event": "test_event",
    "distinct_id": "test-user-1",
    "properties": { "source": "manual_test" },
    "timestamp": "2026-04-04T12:00:00.000Z"
  }'

Mixpanel

curl -X POST https://retivo.ai/api/connectors/mixpanel \
  -H "Authorization: Bearer rt_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "event": "test_event",
    "properties": {
      "distinct_id": "test-user-1",
      "time": 1743782400,
      "source": "manual_test"
    }
  }'

A successful response looks like:

{ "accepted": 1, "users_upserted": 0 }

Event Mapping

Each connector normalizes incoming payloads into Retivo's canonical event format. Here is how events from each platform are mapped.

Segment

• track calls are ingested as Retivo events. The original event name is preserved as-is (e.g., a Segment track call with event "Project Created" becomes a Retivo event named Project Created).
• identify calls create or update the user profile in Retivo. Traits from the identify payload are stored as user properties.
• page calls are normalized to a page_viewed event, with the page name and URL included in event properties.

PostHog

• Custom events (e.g., project_created) are ingested as Retivo events with the original event name preserved.
• $pageview events are normalized to a page_viewed event.
• $identify events create or update the user profile in Retivo. Properties in $set and $set_once are stored as user traits.
• Other internal PostHog events (names starting with $) are skipped.

Mixpanel

• All Mixpanel events are ingested as Retivo events with the original event name preserved (e.g., "Project Created" stays Project Created).
• The distinct_id property identifies the user, and time is converted from Unix seconds to an ISO timestamp.