{"id":1147,"date":"2026-05-21T13:00:00","date_gmt":"2026-05-21T18:00:00","guid":{"rendered":"https:\/\/tolinku.com\/blog\/?p=1147"},"modified":"2026-03-07T03:34:57","modified_gmt":"2026-03-07T08:34:57","slug":"webhook-attribution","status":"publish","type":"post","link":"https:\/\/tolinku.com\/blog\/webhook-attribution\/","title":{"rendered":"Attribution via Webhooks: Real-Time Conversion Tracking"},"content":{"rendered":"\n

Attribution answers the question "where did this user come from?" Webhooks answer the question "when?" Together, they give you real-time conversion tracking: the moment a user installs your app, completes a referral, or claims a deferred deep link, you know about it and you know which campaign, channel, and link brought them in.<\/p>\n\n\n\n

This guide covers how to use Tolinku webhooks<\/a> for real-time attribution, how to build an attribution data model, and how to connect webhook events to campaign optimization workflows. For the general webhook setup, see the webhook setup guide<\/a>. For a broader overview of mobile attribution, see the mobile attribution developer's guide<\/a>.<\/p>\n\n\n\n

\"Tolinku\nThe webhooks page with create form, webhook list, and delivery log.<\/em><\/p>\n\n\n\n

The Attribution Events<\/h2>\n\n\n\n

Tolinku fires five webhook events. Each one carries attribution context in the data<\/code> object:<\/p>\n\n\n\n

link.clicked<\/code><\/h3>\n\n\n\n

Fires when a user taps or clicks a deep link. This is the top of your attribution funnel.<\/p>\n\n\n\n

{\n  "event": "link.clicked",\n  "timestamp": "2026-05-21T14:00:00.000Z",\n  "data": {\n    "prefix": "go",\n    "token": "summer-sale",\n    "hostname": "links.example.com",\n    "ip": "203.0.113.42",\n    "platform": "ios",\n    "device_type": "mobile",\n    "campaign": "instagram-story-may"\n  }\n}\n<\/code><\/pre>\n\n\n\n
The campaign<\/code> field corresponds to the campaign parameter configured on the link. The prefix<\/code> and token<\/code> together identify the specific route that was clicked (e.g., go\/summer-sale<\/code>).<\/p>\n\n\n\n
deferred_link.claimed<\/code><\/h3>\n\n\n\n
Fires when a deferred deep link is resolved after app install. This event proves that a pre-install click led to an actual install and app open.<\/p>\n\n\n\n
install.tracked<\/code><\/h3>\n\n\n\n
Fires when an app install is attributed to a deep link. This is the core conversion event for user acquisition campaigns.<\/p>\n\n\n\n
referral.created<\/code><\/h3>\n\n\n\n
Fires when a new referral is registered. The referred user clicked a referral link and started the signup process.<\/p>\n\n\n\n
referral.completed<\/code><\/h3>\n\n\n\n
Fires when a referred user completes the target action (first purchase, subscription, etc.). This is the bottom of the referral attribution funnel.<\/p>\n\n\n\n
See the webhook event types guide<\/a> for full payload documentation.<\/p>\n\n\n\n
Building an Attribution Model<\/h2>\n\n\n\n
For real-time attribution, you need to connect events across the funnel. A single user journey might produce this sequence:<\/p>\n\n\n\n
    \n
  1. link.clicked<\/code> (user taps a campaign link)<\/li>\n
  2. deferred_link.claimed<\/code> (user installs and opens the app; the original click is resolved)<\/li>\n
  3. install.tracked<\/code> (install is attributed)<\/li>\n
  4. referral.completed<\/code> (if this was a referral link, the conversion fires)<\/li>\n<\/ol>\n\n\n\n
    The link between these events is the deep link itself: the prefix<\/code>, token<\/code>, and campaign<\/code> fields appear consistently across related events. Your attribution system matches events by these fields to reconstruct the user journey.<\/p>\n\n\n\n
    Attribution Table Schema<\/h3>\n\n\n\n
    CREATE TABLE attribution_events (\n  id SERIAL PRIMARY KEY,\n  event_type VARCHAR(50) NOT NULL,\n  event_timestamp TIMESTAMPTZ NOT NULL,\n  received_at TIMESTAMPTZ DEFAULT NOW(),\n  prefix VARCHAR(100),\n  token VARCHAR(255),\n  hostname VARCHAR(255),\n  campaign VARCHAR(255),\n  platform VARCHAR(20),\n  device_type VARCHAR(20),\n  ip INET,\n  raw_data JSONB NOT NULL\n);\n\nCREATE INDEX idx_attribution_campaign ON attribution_events(campaign);\nCREATE INDEX idx_attribution_token ON attribution_events(token);\nCREATE INDEX idx_attribution_event_type ON attribution_events(event_type);\nCREATE INDEX idx_attribution_timestamp ON attribution_events(event_timestamp);\n<\/code><\/pre>\n\n\n\n
    Receiver<\/h3>\n\n\n\n
    import express from 'express';\nimport crypto from 'crypto';\nimport pg from 'pg';\n\nconst app = express();\napp.use('\/webhooks', express.raw({ type: 'application\/json' }));\n\nconst pool = new pg.Pool({ connectionString: process.env.DATABASE_URL });\nconst WEBHOOK_SECRET = process.env.WEBHOOK_SECRET!;\n\napp.post('\/webhooks\/tolinku', async (req, res) => {\n  const signature = req.headers['x-webhook-signature'] as string;\n  const expected = crypto\n    .createHmac('sha256', WEBHOOK_SECRET)\n    .update(req.body)\n    .digest('hex');\n\n  if (signature !== expected) {\n    return res.status(401).send('Invalid signature');\n  }\n\n  res.status(200).send('OK');\n\n  const event = JSON.parse(req.body.toString());\n  await recordAttribution(event);\n});\n\nasync function recordAttribution(event: any) {\n  const { event: eventType, timestamp, data } = event;\n\n  \/\/ Deduplicate using a hash of the event content\n  const eventHash = crypto\n    .createHash('sha256')\n    .update(JSON.stringify(event))\n    .digest('hex');\n\n  await pool.query(\n    `INSERT INTO attribution_events\n     (event_type, event_timestamp, prefix, token, hostname, campaign,\n      platform, device_type, ip, raw_data)\n     VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10)\n     ON CONFLICT DO NOTHING`,\n    [\n      eventType,\n      timestamp,\n      data.prefix || null,\n      data.token || null,\n      data.hostname || null,\n      data.campaign || null,\n      data.platform || null,\n      data.device_type || null,\n      data.ip || null,\n      JSON.stringify(event),\n    ]\n  );\n}\n<\/code><\/pre>\n\n\n\n
    Last-Click Attribution<\/h2>\n\n\n\n
    The simplest attribution model: credit the conversion to the last link clicked before the conversion event. This is what most teams start with, and it's often sufficient.<\/p>\n\n\n\n
    With webhook data, last-click attribution is straightforward:<\/p>\n\n\n\n
    -- For each install, find the most recent click with the same token\nSELECT\n  i.event_timestamp AS install_time,\n  i.token,\n  i.campaign,\n  i.platform,\n  c.event_timestamp AS click_time,\n  EXTRACT(EPOCH FROM (i.event_timestamp - c.event_timestamp)) AS seconds_to_install\nFROM attribution_events i\nLEFT JOIN LATERAL (\n  SELECT event_timestamp\n  FROM attribution_events\n  WHERE event_type = 'link.clicked'\n    AND token = i.token\n    AND event_timestamp < i.event_timestamp\n  ORDER BY event_timestamp DESC\n  LIMIT 1\n) c ON true\nWHERE i.event_type = 'install.tracked'\n  AND i.event_timestamp > NOW() - INTERVAL '7 days';\n<\/code><\/pre>\n\n\n\n
    This query joins each install event with its most recent preceding click event using the token<\/code> field. The seconds_to_install<\/code> column tells you how long the conversion took.<\/p>\n\n\n\n
    Multi-Touch Attribution<\/h2>\n\n\n\n
    For campaigns that span multiple touchpoints (a user sees an ad, clicks a social post, then clicks a referral link), you want to track all touches, not just the last one.<\/p>\n\n\n\n
    The webhook data alone won't give you the full multi-touch picture, because Tolinku fires webhooks for its own link events. But you can combine webhook data with your other attribution sources to build a multi-touch model:<\/p>\n\n\n\n
    -- All touchpoints for links with the same campaign, ordered by time\nSELECT\n  event_type,\n  event_timestamp,\n  token,\n  campaign,\n  platform,\n  device_type\nFROM attribution_events\nWHERE campaign = 'instagram-story-may'\nORDER BY event_timestamp;\n<\/code><\/pre>\n\n\n\n
    This shows the full journey of a campaign: clicks, deferred link claims, installs, and referral completions over time.<\/p>\n\n\n\n
    Real-Time Campaign Dashboards<\/h2>\n\n\n\n
    The real power of webhook-based attribution is speed. Instead of waiting for a daily batch export, you can build dashboards that update in real time.<\/p>\n\n\n\n
    Conversion Rate by Campaign<\/h3>\n\n\n\n
    SELECT\n  campaign,\n  COUNT(*) FILTER (WHERE event_type = 'link.clicked') AS clicks,\n  COUNT(*) FILTER (WHERE event_type = 'install.tracked') AS installs,\n  COUNT(*) FILTER (WHERE event_type = 'referral.completed') AS conversions,\n  ROUND(\n    COUNT(*) FILTER (WHERE event_type = 'install.tracked')::numeric \/\n    NULLIF(COUNT(*) FILTER (WHERE event_type = 'link.clicked'), 0) * 100,\n    2\n  ) AS install_rate,\n  ROUND(\n    COUNT(*) FILTER (WHERE event_type = 'referral.completed')::numeric \/\n    NULLIF(COUNT(*) FILTER (WHERE event_type = 'install.tracked'), 0) * 100,\n    2\n  ) AS conversion_rate\nFROM attribution_events\nWHERE event_timestamp > NOW() - INTERVAL '24 hours'\n  AND campaign IS NOT NULL\nGROUP BY campaign\nORDER BY clicks DESC;\n<\/code><\/pre>\n\n\n\n
    Platform Breakdown<\/h3>\n\n\n\n
    SELECT\n  platform,\n  device_type,\n  COUNT(*) FILTER (WHERE event_type = 'link.clicked') AS clicks,\n  COUNT(*) FILTER (WHERE event_type = 'install.tracked') AS installs\nFROM attribution_events\nWHERE event_timestamp > NOW() - INTERVAL '7 days'\nGROUP BY platform, device_type\nORDER BY clicks DESC;\n<\/code><\/pre>\n\n\n\n
    Time to Install<\/h3>\n\n\n\n
    SELECT\n  campaign,\n  PERCENTILE_CONT(0.5) WITHIN GROUP (\n    ORDER BY EXTRACT(EPOCH FROM (i.event_timestamp - c.event_timestamp))\n  ) AS median_seconds_to_install\nFROM attribution_events i\nJOIN attribution_events c\n  ON c.event_type = 'link.clicked'\n  AND c.token = i.token\n  AND c.event_timestamp < i.event_timestamp\nWHERE i.event_type = 'install.tracked'\n  AND i.event_timestamp > NOW() - INTERVAL '7 days'\nGROUP BY i.campaign;\n<\/code><\/pre>\n\n\n\n
    Connect these queries to a dashboard tool (Grafana, Metabase, or a custom frontend) and you have real-time attribution reporting.<\/p>\n\n\n\n
    Attribution Windows<\/h2>\n\n\n\n
    An attribution window defines how long after a click you'll still credit a conversion. Without a window, a user who clicked a link six months ago and happens to install your app today would get attributed to that old campaign.<\/p>\n\n\n\n
    Standard attribution windows:<\/p>\n\n\n\n
    \n\n\n\n\n\n
    Event Flow<\/th>\nTypical Window<\/th>\n<\/tr>\n<\/thead>\n
    Click to install<\/td>\n7 days<\/td>\n<\/tr>\n
    Click to deferred link claim<\/td>\n7 days<\/td>\n<\/tr>\n
    Install to referral completion<\/td>\n30 days<\/td>\n<\/tr>\n<\/tbody><\/table><\/figure>\n\n\n\n
    Apply the window in your queries:<\/p>\n\n\n\n
    -- Only attribute installs that happened within 7 days of a click\nSELECT *\nFROM attribution_events i\nJOIN attribution_events c\n  ON c.event_type = 'link.clicked'\n  AND c.token = i.token\n  AND c.event_timestamp < i.event_timestamp\n  AND i.event_timestamp - c.event_timestamp < INTERVAL '7 days'\nWHERE i.event_type = 'install.tracked';\n<\/code><\/pre>\n\n\n\n
    Tolinku's analytics dashboard<\/a> applies similar windows to its built-in attribution reporting.<\/p>\n\n\n\n
    Alerting on Attribution Anomalies<\/h2>\n\n\n\n
    Real-time data enables real-time alerts. Set up monitoring for:<\/p>\n\n\n\n
    Click spike without installs<\/strong>: If link.clicked<\/code> volume surges but install.tracked<\/code> stays flat, something is wrong. Either the landing page is broken, the app store listing isn't converting, or you're getting bot traffic.<\/p>\n\n\n\n
    Sudden conversion drop<\/strong>: If a campaign's conversion rate drops by more than 50% compared to its trailing 7-day average, alert immediately. This could indicate a broken deep link, a misconfigured route, or a tracking issue.<\/p>\n\n\n\n
    Unusual referral patterns<\/strong>: A single referral token generating hundreds of referral.created<\/code> events in an hour could indicate fraud. See the webhook fraud detection<\/a> article for more on this.<\/p>\n\n\n\n
    \/\/ Simple anomaly detection: alert if install rate drops below threshold\nasync function checkConversionHealth(campaign: string) {\n  const result = await pool.query(`\n    SELECT\n      COUNT(*) FILTER (WHERE event_type = 'link.clicked') AS clicks,\n      COUNT(*) FILTER (WHERE event_type = 'install.tracked') AS installs\n    FROM attribution_events\n    WHERE campaign = $1\n      AND event_timestamp > NOW() - INTERVAL '1 hour'\n  `, [campaign]);\n\n  const { clicks, installs } = result.rows[0];\n  const rate = clicks > 0 ? installs \/ clicks : 0;\n\n  if (clicks > 100 && rate < 0.01) {\n    \/\/ Less than 1% install rate on 100+ clicks: something is wrong\n    await sendAlert(`Low install rate for campaign ${campaign}: ${(rate * 100).toFixed(1)}%`);\n  }\n}\n<\/code><\/pre>\n\n\n\n
    Privacy Considerations<\/h2>\n\n\n\n
    Attribution data includes IP addresses and device information. Handle it responsibly:<\/p>\n\n\n\n