Webhooks
Webhooks push real-time events from lnkify to a URL you control, so you can react to link activity in your own systems. They're managed from the Webhooks screen (/webhooks).
Events
| Event | Fires when |
|---|---|
link.created | A new shortlink is created |
link.clicked | A shortlink is visited (and tracking is on) |
bio.viewed | A bio page is viewed |
A webhook subscribes to one or more of these events.
Creating a Webhook
- Open Webhooks from the dashboard sidebar (
/webhooks) - Click Create Webhook
- Enter the URL that should receive events
- Select the events to subscribe to
- Click Create
On creation, a signing secret is generated for the webhook. lnkify uses it to sign every delivery so you can verify authenticity (the secret is shown to you / stored server-side and redacted in API listings).
Delivery Format
Each event is delivered as an HTTP POST with a JSON body and these headers:
| Header | Description |
|---|---|
X-Lnkify-Event | The event name (e.g. link.clicked) |
X-Lnkify-Signature | HMAC-SHA256(secret, raw_body), hex-encoded |
To verify a delivery, compute HMAC-SHA256 of the raw request body using your webhook secret and compare it to X-Lnkify-Signature.
Retries & Timeouts
- Each delivery attempt times out after 10 seconds.
- Failed deliveries are retried up to 3 times with backoff delays of 1s, 5s, then 25s.
- Every attempt is recorded as a delivery with its HTTP status and response body, viewable per webhook (GraphQL
webhookDeliveries(webhookId)).
A delivery counts as successful on a 2xx response; anything else (or a timeout) triggers a retry.
Managing Webhooks
- Disable a webhook to pause deliveries without deleting it (
enabled: false). - Edit the URL or subscribed events at any time.
- Delete a webhook to remove it permanently.
Plan Limits
Webhooks are a Pro-tier feature when billing is enabled (see Billing & Usage):
| Plan | Max webhooks |
|---|---|
| Free | 0 |
| Starter | 0 |
| Pro | 5 |
A default self-hosted instance (BILLING_ENFORCE=false) does not enforce these limits — webhooks are available to all accounts.
Via API / MCP
Webhooks can also be managed programmatically: the GraphQL createWebhook, updateWebhook, deleteWebhook mutations and the webhooks / webhookDeliveries queries (see Mutations), or the MCP create_webhook, list_webhooks, delete_webhook tools (see MCP Tools).
Next: API Keys