Webhooks (Beta)

Webhooks allow you to receive real-time notifications when your links are clicked. When a click occurs, Linkly sends a POST request to your specified URL(s) with detailed information about the click.

Use Cases

Zapier Integration: Trigger Zaps when links are clicked
Custom Analytics: Send click data to your own analytics system
CRM Updates: Update customer records when they click links
Slack Notifications: Get notified in Slack when important links are clicked
Lead Tracking: Track when prospects engage with your links

Setting Up Webhooks

Link-Level Webhooks

To receive notifications for clicks on a specific link:

Go to Links and click on the link you want to configure
Scroll down to the Webhooks (Beta) section
Enter your webhook URL(s), one per line
Click Save Link

Link-level webhooks only fire when that specific link is clicked.

Workspace-Level Webhooks

To receive notifications for all clicks across your entire workspace:

Go to Settings (gear icon in the sidebar)
Find the Webhooks (Beta) field
Enter your webhook URL(s), one per line
Click Save Settings

Workspace-level webhooks fire for every click on any link in your workspace.

Note: If you configure webhooks at both levels, both will fire for clicks on that link.

Webhook Payload

When a click occurs, Linkly sends a POST request with the following JSON payload:

{
  "event": "click",
  "timestamp": "2025-01-15T10:30:00Z",
  "link": {
    "id": 12345,
    "name": "My Campaign Link",
    "url": "https://example.com/landing-page",
    "full_url": "https://yourdomain.com/abc123",
    "domain": "yourdomain.com",
    "slug": "/abc123",
    "destination": "https://example.com/landing-page",
    "workspace_id": 1,
    "enabled": true,
    "cloaking": false,
    "forward_params": true,
    "block_bots": true,
    "public_analytics": false,
    "utm_source": "newsletter",
    "utm_medium": "email",
    "utm_campaign": "spring-sale",
    "og_title": "Special Offer",
    "og_description": "Check out our spring sale!",
    "rules": [
      {
        "what": "country",
        "matches": "US",
        "url": "https://example.com/us-landing"
      }
    ]
  },
  "click": {
    "country": "US",
    "is_eu_country": false,
    "platform": "desktop",
    "browser_name": "Chrome",
    "referer": "https://twitter.com/",
    "isp": "Comcast",
    "bot_name": null,
    "destination": "https://example.com/landing-page",
    "params": {
      "utm_source": "twitter"
    }
  }
}

Payload Fields

Event Info

Field	Description
`event`	Always "click"
`timestamp`	ISO 8601 timestamp of the click

← Scroll →

Link Object

Field	Description
`id`	Unique link identifier
`name`	Link nickname
`url`	Original destination URL
`full_url`	The short link URL
`domain`	Custom domain (if configured)
`slug`	URL path/slug
`destination`	Actual destination for this click (may differ from `url` if rules applied)
`workspace_id`	Workspace identifier
`enabled`	Whether link is active
`rules`	Array of redirect rules (geo, device, rotator)
`utm_*`	UTM parameters if configured
`og_*`	Open Graph settings if configured

← Scroll →

Click Object

Field	Description
`country`	Two-letter country code (e.g., "US", "GB")
`is_eu_country`	Whether click originated from EU
`platform`	Device platform (desktop, ios, android, etc.)
`browser_name`	Browser name (Chrome, Safari, Firefox, etc.)
`referer`	Referring URL (if available)
`isp`	Internet Service Provider
`bot_name`	Bot identifier (null for human clicks)
`destination`	Final destination URL for this click
`params`	Query parameters passed to the link

← Scroll →

Privacy Note: IP addresses are never included in webhook payloads.

Zapier Integration

For Zapier, use our native Zapier integration which includes instant click triggers powered by webhooks.

Best Practices

Multiple Webhooks

You can add multiple webhook URLs (one per line). All URLs will receive the same payload when a click occurs.

Error Handling

Webhooks are fire-and-forget - Linkly does not retry failed deliveries
Webhook failures never affect the redirect - users always reach their destination
Ensure your webhook endpoint responds quickly (< 5 seconds recommended)

Security

Use HTTPS endpoints for webhook URLs
Validate incoming requests in your webhook handler
Consider adding a secret parameter to your webhook URL for verification

Testing

Set up a webhook URL using a service like webhook.site or RequestBin
Click your link
Inspect the received payload
Once verified, switch to your production webhook URL

Troubleshooting

Webhooks Not Firing

Check the URL: Ensure your webhook URL is valid and accessible
Check link settings: Verify webhooks are saved on the link or workspace
Check click recording: Webhooks only fire when clicks are recorded (not for excluded IPs or skipped crawlers)

Missing Data

Some fields may be null if:

The information wasn't available (e.g., no referer)
Privacy settings prevented collection
The click was from a bot (bot_name will be populated instead)

Limitations

No retries: Failed webhook deliveries are not retried
No delivery confirmation: Linkly does not track webhook delivery status
5-second timeout: Webhook requests timeout after 5 seconds
Beta feature: This feature is in beta and may change

API Access

You can also manage webhooks programmatically via the API:

POST   /api/v1/link/:link_id/webhooks
DELETE /api/v1/link/:link_id/webhooks/:hook_id
GET    /api/v1/link/:link_id/webhooks

POST   /api/v1/workspace/:workspace_id/webhooks
DELETE /api/v1/workspace/:workspace_id/webhooks/:hook_id
GET    /api/v1/workspace/:workspace_id/webhooks

See the API Documentation for details.