Webhooks
Secure links with powerful analytics. Configure real-time event notifications for your Linkify projects.
Configure WebhookHow to connect your endpoint
Linkify sends HTTP POST requests to your designated URL whenever a tracked event occurs. The system supports Bearer token authentication, exponential backoff retries, and HMAC-SHA256 signature verification for enterprise-grade security.
Step 1: Define your endpoint
Enter a valid HTTPS address in the API dashboard, such as `https://api.novatech.io/v1/hooks/linkify`. Port 443 is mandatory, and internal RFC1918 IP ranges are blocked by default.
Step 2: Select trigger events
Enable `link.click` to track visitor interactions and `link.created` to sync newly generated short URLs with your CRM, data warehouse, or notification service.
Step 3: Secure the payload
Generate a `whsec_...` signing key in the settings. Linkify attaches this to the `X-Linkify-Signature-256` header so your server can verify request authenticity before processing.
Request structure & data schema
Every webhook delivery includes event metadata, project identifiers, and contextual payload details. Below are production-ready JSON examples for the `link.click` and `link.created` triggers.
Event: link.click
Dispatched immediately when a user follows a shortened link. Contains geolocation, device fingerprint, UTM parameters, and precise timestamps.
Sample JSON:
{"event":"link.click","id":"evt_8f3a9c2d1e","timestamp":"2024-11-15T14:32:08Z","project_id":"prj_novatech_marketing","payload":{"short_url":"https://lnk.fi/xK9mP","destination":"https://shop.example.com/autumn-sale","ip":"84.23.112.45","country":"DE","city":"Berlin","user_agent":"Mozilla/5.0 (iPhone; CPU iPhone OS 17_1 like Mac OS X)","referring_domain":"t.me","utm_source":"telegram","utm_campaign":"fall_promo"}}
Event: link.created
Fires instantly after a short link is generated via the API or dashboard. Includes expiration rules, custom domain assignments, and creator metadata.
Sample JSON:
{"event":"link.created","id":"evt_7b2c4a1f0d","timestamp":"2024-11-15T14:30:55Z","project_id":"prj_novatech_marketing","payload":{"short_url":"https://lnk.fi/xK9mP","destination":"https://shop.example.com/autumn-sale","alias":"autumn-sale","custom_domain":"go.novatech.io","expires_at":"2025-02-28T23:59:59Z","created_by":"api_key_7742","tags":["promo","q4","telegram"],"qr_enabled":true}}
All requests ship with `Content-Type: application/json`. Failed deliveries (5xx responses) are retried up to five times at 1h, 4h, 12h, 24h, and 48h intervals. Successful processing requires a 200–299 HTTP status code.
Read Full API Documentation