API reference

Integrations

Inbound webhooks from other tools.

Receive PostHog events#

post/webhooks/posthog

Target for a PostHog webhook destination. Server to server: no CORS or Allowed origin. Field limits match POST /events, but long values are cut rather than refused so a delivery is never rejected for length. Events for erased end users are dropped and counted under suppressed.

Auth: public key + X-Tug-Webhook-Secret.

Parameters

  • ?publicKeystringrequired

    The project's public key (part of the webhook URL Tug shows you).

Body

PostHogWrappedEvent: PostHog's destination shape. Other top-level keys (person, …) are ignored.

  • eventobjectrequired

PostHogFlatEvent: One event at the top level.

  • uuidstring

    PostHog's event id. Stored as the idempotency key (ph:<uuid>), so retries are stored once. Send it.

  • eventstringrequired

    Event name. Longer than 200 characters is cut.

  • distinct_idstringrequired

    PostHog distinct id. Longer than 256 characters is cut.

  • timestampstring

    When it happened, ISO 8601. Defaults to when Tug receives it.

  • propertiesobject | string

    Properties, or a JSON string of them. $-prefixed keys are dropped except $current_url, which becomes url (cut to 2048 characters). Nested objects and arrays are dropped. Tug adds source: "posthog".

Or an array of up to 100 of PostHogWrappedEvent | PostHogFlatEvent

curl -X POST "https://tughq.com/api/v1/webhooks/posthog?publicKey=phk_live_3kV9xQmR2pT8wYc1Ld5NbA" \
  -H "X-Tug-Webhook-Secret: fwh_q8Zr3mN6vB1xK4cT7yW0pL2s" \
  -H "Content-Type: application/json" \
  -d '{
    "event": {
      "uuid": "01936f0e-5a7b-7c3d-9e1f-2a3b4c5d6e7f",
      "event": "signup_completed",
      "distinct_id": "user_abc",
      "timestamp": "2026-11-22T12:00:00.000Z",
      "properties": {
        "plan": "pro"
      }
    }
  }'

200 response · JSON

{
  "ok": true,
  "accepted": 1,
  "suppressed": 0
}

Errors: invalid_json (400), invalid_request (400), missing_public_key (400), invalid_public_key (401), trial_expired (402), billing_inactive (402), plan_limit_reached (402), webhook_not_enabled (403), payload_too_large (413), internal_error (500), service_unavailable (503).

  • 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