App installed (app.installed)

Description

Triggered when a mobile app installation is attributed to a ChottuLink short link (install tracked with platform and attribution metadata). The payload may include the resolved destination URL with UTM parameters, the client IP, and coarse geographic context in location when available.

Payload structure

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

Fields

Root (envelope)

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

Payload object (payload)

Field	Type	Description
attributionType	string	Attribution classification: ATTRIBUTED or ORGANIC.
clickedShortUrl	string	Short URL associated with the attributed install (may match shortUrl).
destinationUrlWithUtm	string	Landing URL including UTM and similar query parameters when resolved.
deviceId	string	Device identifier for the install (UUID string).
installId	string	Identifier for this install record (UUID string).
ip	string	Client IP observed for attribution when available.
location	object	Coarse geographic enrichment for the IP (see below).
platform	string	Platform name (for example android).
shortUrl	string	Short URL attributed for this install.
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 Asia/Kolkata).

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": "0a213a59-2a4a-40e3-a851-e0e183338cc6",
  "eventType": "app.installed",
  "schemaVersion": 1,
  "timestamp": "2026-05-13T08:23:48.750521",
  "payload": {
    "attributionType": "ATTRIBUTED",
    "clickedShortUrl": "https://tenant.example.invalid/install-demo",
    "destinationUrlWithUtm": "https://destination.example.invalid/landing?utm_source=test&utm_medium=test",
    "deviceId": "67b59be0-24f1-40f8-883c-e8a248fc2681",
    "installId": "f12f1932-fc72-4409-9c78-eefff2f1622b",
    "ip": "198.51.100.42",
    "location": {
      "city": "Test City",
      "country": "Testland",
      "country_code": "TL",
      "latitude": 40.7128,
      "longitude": -74.006,
      "state": "Test Region",
      "timezone": "Etc/UTC"
    },
    "platform": "android",
    "shortUrl": "https://tenant.example.invalid/install-demo",
    "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

• Allowed values for attributionType and platform should be validated against your backend or SDK contracts beyond this sample.
• destinationUrlWithUtm may omit or alter query parameters depending on product configuration; treat resolution as authoritative only after confirming behavior with the API or SDK contract you use.