Attribution Passthrough

Clients can pass their own marketing tracking codes on a journey link. Telegra captures them without interpreting keys, stores first- and last-touch on the journey (and order), and returns them in journey webhooks.

Journey events that include this schema use api_version "2026-08-06". Consumers must accept that version (and may ignore unknown fields). Compatibility with older consumers is limited to clients that already accept "2026-08-06" and ignore unknown fields such as attribution.

Sending tracking codes in

Append query parameters to any journey storefront URL. No per-client Telegra configuration is required.

Captured parameters

Standard utm_* parameters no longer need a telegra_ prefix. Both forms are accepted and both are returned. If you send utm_source and telegra_utm_source, you get both back as separate keys — Telegra does not merge or deduplicate them.

Recognition is case-insensitive, because platforms disagree on casing for what they append (Snapchat sends ScCid). Keys are stored and returned exactly as you sent them, so UTM_Source comes back as UTM_Source.

⚠️

Do not put PHI, patient identifiers, or other sensitive data in attribution inputs. Use only non-sensitive campaign identifiers (UTM-style tags, ad click IDs, and Meta fbp/fbc cookie values). Telegra stores and re-emits accepted params verbatim — it does not scrub health or identity content from these keys.

Validation limits

Invalid or excess parameters are dropped silently. The journey still loads.

Example URL

https://shop.example.com/weight-loss?telegra_utm_source=google&telegra_utm_medium=cpc&telegra_utm_campaign=spring_wl&gclid=Cj0KCQexample&fbclid=IwARexample

The storefront forwards a single JSON attribution query parameter to Telegra along with track and visitorId (used to distinguish first vs repeat visits for the same browser).

Receiving them back

All three journey events use api_version "2026-08-06", whether or not an attribution block is present:

• journey_checkout_started
• journey_completed
• journey_abandoned — use abandoned-journey attribution for retargeting

When attribution was captured for a journey, the payload includes an attribution block. When a journey has no attribution, the attribution key is omitted entirely (not an empty object). Omission does not change api_version.

Shape

{
  "attribution": {
    "first": {
      "captured_at": "2026-01-04T10:22:31.000Z",
      "params": {
        "telegra_utm_source": "google",
        "telegra_utm_medium": "cpc",
        "gclid": "Cj0KCQexample",
        "fbp": "fb.1.1700000000.1234567890"
      }
    },
    "last": {
      "captured_at": "2026-03-11T18:02:55.000Z",
      "params": {
        "telegra_utm_source": "facebook",
        "fbclid": "IwARexample",
        "fbp": "fb.1.1700000000.1234567890",
        "fbc": "fb.1.1700000000.IwARexample"
      }
    },
    "touch_count": 2,
    "visitor_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

⚠️

first.params and last.params must not contain PHI, patient identifiers, or other sensitive data. The complete attribution object is permitted by the JOURNEY v2 allowlist and is delivered nested as shown when present.

Why both first and last touch

• first answers the acquisition question — which channel originally brought the patient.
• last is the latest captured parameter set. It may include non-click values such as telegra_*, fbp, or fbc. A gclid or fbclid appears in last.params only when that latest touch contained one — not because last touch always represents the click immediately before conversion. Prefer last when replaying a click ID to an ad platform so you do not credit a stale first-touch click.

Subscription renewals inherit the parent order's attribution (same first/last block). See Where attribution appears.

Where attribution appears

Attribution is not limited to journey events. Any event tied to a journey or one of its orders carries the same block:

The order is the preferred source, so a subscription renewal carries the attribution of the order that created it — the acquisition campaign stays attached for the life of the subscription. Journey data is used as a fallback for events fired before an order exists.

journey_id and ecommerce_order_id are provided so you can stitch an order-side event back to the journey webhook that carried the same codes.

Non-journey event families use api_version "2026-08-09". This is an additive change: consumers that ignore unknown fields are unaffected.

Compliance guidance

⚠️

Required reading before forwarding click IDs to ad platforms.

Journey webhook payloads may include patient_id and patient_external_id (conditional — present when the journey has a linked patient) and include patient_marketing_consent. When patient_id or patient_external_id is present, the webhook contains identified patient data, whether or not attribution is present. When attribution is also present, it arrives alongside that data.

• Do not forward the webhook payload as-is to Meta Conversions API, Google Ads, or any other advertising platform.
• Extract the click ID (or other tracking token) you need and send that alone, using only data your own privacy program permits.
• Neither Google nor Meta signs a BAA covering their advertising products, including Conversions API. Anything sent to those platforms must be de-identified under your own policies.
• Attribution now also travels on clinical event families — prescription, pharmacy, shipping and lab — because those events hang off an attributed order. A payload can therefore pair a campaign identifier with a clinical status such as a prescription approval. That is appropriate over your authenticated endpoint, but it makes the "extract the token, forward nothing else" rule above more important, not less.
• Telegra's role is a conduit: it returns your own tokens to you over your authenticated webhook endpoint and transmits nothing to ad platforms. Responsibility for what leaves your systems rests with you.