Link clicked (link.clicked)

Description

Triggered when an end user clicks a short link and ChottuLink records the click (including device and coarse geographic context when available).

Payload structure

{
  "eventId": "string (uuid)",
  "eventType": "link.clicked",
  "timestamp": "string (ISO-8601)",
  "schemaVersion": 1,
  "payload": {}
}

Fields

Root (envelope)

Field	Type	Description
eventId	string	Unique identifier for this webhook delivery.
eventType	string	Always link.clicked for this event.
timestamp	string	Time the event was emitted.
schemaVersion	number	Version of schema.
payload	object	Click details.

Payload object (payload)

Field	Type	Description
shortUrl	string	Canonical short URL for the link.
clickedShortUrl	string	Short URL as requested when the click occurred (may match shortUrl).
handledBy	string	Channel or handler that processed the click (for example web).
ip	string	Client IP observed for the click.
location	object	Coarse geographic enrichment for the IP (see below).
userAgent	string	Raw User-Agent header when available.
adIds	object	Attribution click IDs captured from the link or session (see below).

payload.location

Field	Type	Description
city	string	City name derived from geo lookup.
state	string	Region or state name.
country	string	Country name.
country_code	string	ISO-style country code (for example IN).
latitude	number	Approximate latitude.
longitude	number	Approximate longitude.
timezone	string	IANA timezone identifier when resolved (for example America/Denver).

payload.adIds

Field	Type	Description
fbclid	string | null	Meta — Facebook Click Identifier. Used by Meta Pixel / Conversions API (CAPI) to attribute conversions to Facebook/Instagram ads.
gclid	string | null	Google Ads — Google Click Identifier. Used for offline conversions and campaign performance tracking.
gbraid	string | null	Google Ads — App iOS Click ID. For iOS 14.5+ traffic directed to an app; supports privacy-compliant modeled attribution.
wbraid	string | null	Google Ads — Web iOS Click ID. For iOS 14.5+ traffic directed to a website; supports privacy-compliant modeled attribution.
ttclid	string | null	TikTok — TikTok Click ID. Used by TikTok Pixel and Events API to link actions back to TikTok campaigns.

Working with Ad Click IDs

payload.adIds carries click identifiers from ad platforms (Meta, Google, TikTok) when they were present on the attributed link. In production, expect at most one non-null value — the platform that actually drove the click.

Rules for consumers

• One active ID per event — adIds is mutually exclusive in production. Only one key holds a non-null string; the rest are null. That value identifies which ad network drove the session.
• Google uses exactly one ID type — gclid, gbraid, and wbraid are never set together. Google assigns one based on traffic type:
  • Desktop or Android web/app → gclid
  • iOS web (Safari) → wbraid
  • iOS in-app deep link → gbraid
• Route by non-null key — Send the populated ID to the matching downstream system (Meta CAPI, Google Ads offline conversions, TikTok Events API, CRM, data warehouse, etc.). Ignore keys that are null.

Typical production shapes

Scenario A — Meta ad (Instagram / Facebook)

{
  "adIds": {
    "fbclid": "IwAR2xK9aBc123xyz456_ExampleString_789",
    "gclid": null,
    "gbraid": null,
    "wbraid": null,
    "ttclid": null
  }
}

Scenario B — Google Search ad on iPhone (web)

{
  "adIds": {
    "fbclid": null,
    "gclid": null,
    "gbraid": null,
    "wbraid": "ClgKCQjwhO3DBhDaARJHAPBAqMmEZWE7Gt_zJEt",
    "ttclid": null
  }
}

note

The full example payload below shows every adIds key populated for complete schema reference. In live traffic, only one key will be non-null at a time.

Example payload

{
  "eventId": "e68fc144-7f32-4b5e-97a0-616954ff0daa",
  "eventType": "link.clicked",
  "schemaVersion": 1,
  "timestamp": "2026-04-29T12:53:02.916526",
  "payload": {
    "shortUrl": "https://zeustechnology.trycleansify.com/profileManager",
    "clickedShortUrl": "https://zeustechnology.trycleansify.com/profileManager",
    "handledBy": "web",
    "ip": "49.47.11.96",
    "location": {
      "city": "Bhilai",
      "state": "Chhattisgarh",
      "country": "India",
      "country_code": "IN",
      "latitude": 21.2129,
      "longitude": 81.4293,
      "timezone": "America/Denver"
    },
    "userAgent": "Mozilla/5.0 (Linux; Android 14; K) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/147.0.7727.111 Mobile Safari/537.36",
    "adIds": {
      "fbclid": "IwY2xjawR9OhlleHRuA2FlbQIxMQBzcnRjBmFwcF9pZAwzNTA2ODU1MzE3MjgAAR7PIdCfTw5a8i37AfDaVlZLvWaMdJwQEr75JEPtbfWcTrnPaUu7Tpj_3OvS-A_aem_0FItaF20o94lSQX6izgv5g",
      "gclid": "EAIaIQobChMIu_v0r_f9_wIVh7LICh0wQQT_EAAYASAAEgK_v_D_BwE",
      "gbraid": "0AAAAACZGY6vERiXMMTJYoB2VG86-qHLmR",
      "wbraid": "ClgKCQjwhO3DBhDaARJHAPBAqMmEZWE7Gt_zJEt",
      "ttclid": "1766471830193154_1_726359051_1"
    }
  }
}

Notes

• Geo fields depend on successful IP resolution; consumers should tolerate missing or coarse values if your deployment differs.