Guides

PostHog

Forward PostHog events into Tug with a webhook destination. Keep PostHog for analytics.

Forwarding is included on every plan. Cohorts, intelligence and decisions then run on the same events as your PostHog analytics, without replacing it.

Enable forwarding#

  1. Open your project in Tug.
  2. Under Connect PostHog, click Enable PostHog forwarding.
  3. Copy the two values it shows: the Webhook URL (it includes your publicKey) and the X-Tug-Webhook-Secret header value (starts with fwh_).

Create the destination#

In PostHog, open Data pipeline, then Destinations, and add an HTTP Webhook destination:

URLThe Tug webhook URL, exactly as copied.
MethodPOST
HeadersX-Tug-Webhook-Secret with the secret from Tug (not your PostHog API key).
BodyThe JSON below (also shown on your project page).

PostHog destination body · JSON

{
  "event": {
    "uuid": "{event.uuid}",
    "event": "{event.event}",
    "distinct_id": "{event.distinct_id}",
    "timestamp": "{event.timestamp}",
    "properties": "{event.properties}"
  }
}

PostHog fills in {event.uuid}, {event.event} and the rest at send time.

Optional: add destination filters to forward only some events (for example, leave out $feature_flag_called) and use fewer of your Tug events.

What Tug does with each delivery#

  1. Checks the publicKey in the URL and the X-Tug-Webhook-Secret header against the project.
  2. Parses the body into one or more events: wrapped as above, a flat event, or an array of either (see the reference).
  3. Applies the same field limits as POST /events, except that a long event name, distinct ID or URL is cut to 200, 256 and 2048 characters instead of refused. A bad timestamp or a NUL character is still a 400 that names the field.
  4. Counts the events toward your monthly events like SDK calls, and drops (and counts) events for erased end users.
  5. Stores them, updates the user's last seen time, and runs conversion attribution.

Webhook calls are server to server: no CORS and no Allowed origin check. PostHog retries failed deliveries, so a brief 500 or 503doesn't lose events.

Property handling#

  • Properties starting with $ are dropped, except $current_url, which becomes the event's url.
  • String, number and boolean properties are kept. Nested objects and arrays are dropped.
  • properties sent as a JSON string (common with template substitution) is parsed.
  • Every forwarded event gets properties.source = "posthog", so cohort rules can tell it apart.

Check it works#

  1. Trigger an event in PostHog, or use the destination's test mode.
  2. On your project page, check Recent events. Forwarded events appear within seconds, and Connect PostHog shows when the last one arrived.
  3. Run intelligence (or wait for the daily run), approve a message and preview it for that user ID.

Getting 401, 403 or 400? See Troubleshooting.

  • PageOverviewGet started
  • PageQuick startGet started
  • PageConceptsGet started
  • PageScript tag (tug.js)Install
  • PageReactInstall
  • PageNode and serverInstall
  • PageIdentity verificationGuides
  • PageCounting and holdoutsGuides
  • PagePostHogGuides
  • PageEnvironmentsGuides
  • PageData requestsGuides
  • PageOperator consoleGuides