{"id":1159,"date":"2026-05-22T17:00:00","date_gmt":"2026-05-22T22:00:00","guid":{"rendered":"https:\/\/tolinku.com\/blog\/?p=1159"},"modified":"2026-03-07T03:34:58","modified_gmt":"2026-03-07T08:34:58","slug":"webhook-payload-formats","status":"publish","type":"post","link":"https:\/\/tolinku.com\/blog\/webhook-payload-formats\/","title":{"rendered":"Webhook Payload Formats: Parsing Deep Link Event Data"},"content":{"rendered":"\n

Every webhook integration starts with the same question: what does the payload look like? This reference covers the exact structure of every Tolinku webhook<\/a> event, with TypeScript types, field descriptions, and parsing patterns. Bookmark this page. You'll come back to it every time you add a new event handler.<\/p>\n\n\n\n

For setup instructions, see the webhook setup guide<\/a>. For the full list of events and when they fire, see the webhook event types 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

Envelope Structure<\/h2>\n\n\n\n

Every webhook delivery uses the same envelope format, regardless of event type:<\/p>\n\n\n\n

{\n  "event": "link.clicked",\n  "timestamp": "2026-05-22T14:30:00.000Z",\n  "data": { ... }\n}\n<\/code><\/pre>\n\n\n\n
\n\n\n\n\n\n
Field<\/th>\nType<\/th>\nDescription<\/th>\n<\/tr>\n<\/thead>\n
event<\/code><\/td>\nstring<\/td>\nThe event type identifier<\/td>\n<\/tr>\n
timestamp<\/code><\/td>\nstring (ISO 8601)<\/td>\nWhen the event occurred, in UTC<\/td>\n<\/tr>\n
data<\/code><\/td>\nobject<\/td>\nEvent-specific payload data<\/td>\n<\/tr>\n<\/tbody><\/table><\/figure>\n\n\n\n
The event<\/code> field is also sent in the X-Webhook-Event<\/code> HTTP header, so you can route events before parsing the body.<\/p>\n\n\n\n
TypeScript Types<\/h3>\n\n\n\n
interface WebhookEnvelope {\n  event: WebhookEventType;\n  timestamp: string; \/\/ ISO 8601\n  data: Record<string, unknown>;\n}\n\ntype WebhookEventType =\n  | 'link.clicked'\n  | 'deferred_link.claimed'\n  | 'install.tracked'\n  | 'referral.created'\n  | 'referral.completed'\n  | 'test';\n<\/code><\/pre>\n\n\n\n
HTTP Headers<\/h2>\n\n\n\n
Every webhook delivery includes these headers:<\/p>\n\n\n\n
\n\n\n\n\n\n\n
Header<\/th>\nExample<\/th>\nDescription<\/th>\n<\/tr>\n<\/thead>\n
Content-Type<\/code><\/td>\napplication\/json<\/code><\/td>\nAlways JSON<\/td>\n<\/tr>\n
X-Webhook-Signature<\/code><\/td>\na1b2c3d4e5...<\/code><\/td>\nHMAC-SHA256 hex digest of the request body<\/td>\n<\/tr>\n
X-Webhook-Event<\/code><\/td>\nlink.clicked<\/code><\/td>\nThe event type (matches event<\/code> field in body)<\/td>\n<\/tr>\n
User-Agent<\/code><\/td>\nTolinku\/1.0<\/code><\/td>\nIdentifies the request as from Tolinku<\/td>\n<\/tr>\n<\/tbody><\/table><\/figure>\n\n\n\n
The signature is computed as:<\/p>\n\n\n\n
import crypto from 'crypto';\n\nconst signature = crypto\n  .createHmac('sha256', webhookSecret) \/\/ Your whsec_... secret\n  .update(rawRequestBody)              \/\/ The raw bytes, not parsed JSON\n  .digest('hex');\n<\/code><\/pre>\n\n\n\n
See the webhook security guide<\/a> for full verification code.<\/p>\n\n\n\n
Event: link.clicked<\/code><\/h2>\n\n\n\n
Fires when a user taps or clicks a deep link managed by Tolinku.<\/p>\n\n\n\n
{\n  "event": "link.clicked",\n  "timestamp": "2026-05-22T14:30: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
Field Reference<\/h3>\n\n\n\n
\n\n\n\n\n\n\n\n\n\n
Field<\/th>\nType<\/th>\nDescription<\/th>\n<\/tr>\n<\/thead>\n
data.prefix<\/code><\/td>\nstring<\/td>\nThe route prefix (the first path segment of the deep link URL)<\/td>\n<\/tr>\n
data.token<\/code><\/td>\nstring<\/td>\nThe route token (the second path segment, identifying the specific link)<\/td>\n<\/tr>\n
data.hostname<\/code><\/td>\nstring<\/td>\nThe hostname the link was served from<\/td>\n<\/tr>\n
data.ip<\/code><\/td>\nstring<\/td>\nThe IP address of the user who clicked<\/td>\n<\/tr>\n
data.platform<\/code><\/td>\nstring<\/td>\nDetected platform: ios<\/code>, android<\/code>, or web<\/code><\/td>\n<\/tr>\n
data.device_type<\/code><\/td>\nstring<\/td>\nDevice classification: mobile<\/code>, tablet<\/code>, or desktop<\/code><\/td>\n<\/tr>\n
data.campaign<\/code><\/td>\nstring or null<\/td>\nCampaign identifier if one was configured on the route<\/td>\n<\/tr>\n<\/tbody><\/table><\/figure>\n\n\n\n
TypeScript<\/h3>\n\n\n\n
interface LinkClickedData {\n  prefix: string;\n  token: string;\n  hostname: string;\n  ip: string;\n  platform: 'ios' | 'android' | 'web';\n  device_type: 'mobile' | 'tablet' | 'desktop';\n  campaign: string | null;\n}\n<\/code><\/pre>\n\n\n\n
Notes<\/h3>\n\n\n\n