# Link Tracking Webhooks: Real-Time Click Events for Developers

> A developer's guide to link tracking webhooks: how they work, how to verify HMAC signatures, how retries and idempotency work, and how to wire them up.

URL: https://u2l.ai/blog/webhooks-link-tracking
Published: 2026-11-17T20:19:49+05:30
Updated: 2026-11-17T20:19:49+05:30
Author: Team U2L
Category: developer
Tags: webhooks, link-tracking, developer, api, real-time

---


<!-- TECH_ARTICLE -->
<!-- SOFTWARE_SCHEMA: U2L AI, UtilitiesApplication, Web -->

<!-- SPEAKABLE_START -->
A link tracking webhook is an HTTP callback that fires the moment something happens to one of your short links. Instead of polling an analytics endpoint every few minutes to see what changed, you register an HTTPS URL once, and the shortener POSTs a signed JSON payload to it in near real time. The two common families of events are lifecycle events (`link.created`, `link.updated`, `link.deleted`) that fire when a link is managed through the dashboard or API, and click events that fire when a visitor actually hits the redirect. A well-built provider signs the payload with HMAC-SHA256 so you can verify it was really them.
<!-- SPEAKABLE_END -->

<!-- ABOUT: Webhook, https://en.wikipedia.org/wiki/Webhook -->
<!-- ABOUT: HMAC, https://en.wikipedia.org/wiki/HMAC -->
<!-- ABOUT: HTTP, https://en.wikipedia.org/wiki/HTTP -->
<!-- MENTIONS: HMAC-SHA256, https://en.wikipedia.org/wiki/HMAC -->
<!-- MENTIONS: Representational State Transfer, https://en.wikipedia.org/wiki/REST -->
<!-- MENTIONS: Idempotence, https://en.wikipedia.org/wiki/Idempotence -->

Polling an analytics API every two minutes to find out that a link got clicked at 10:14:03 is one of those things that works until it doesn't. The clock skews. Rate limits throttle the loop. The dashboard runs behind. Somewhere between the fifth and the fiftieth integration you build on top of a URL shortener, you give up and ask: can the shortener just tell me when something happens? That is what a **link tracking webhook** does, and if you've never wired one up, this guide is the one you want open while you do.

What follows is a developer-first walkthrough, not a marketing brochure. We'll cover what a link tracking webhook actually looks like on the wire, which events the major providers emit, how HMAC signature verification works end to end, how to handle retries and idempotency without duplicating side effects, and the production traps that always surprise people the first time they ship this. The last sections are a working reference for setting one up on U2L AI, which is our shortener. All code is runnable; copy it, change the secret, and it works.

## Table of Contents

- [What Is a Link Tracking Webhook?](#what-is-a-link-tracking-webhook)
- [Webhooks vs Polling the Analytics API](#webhooks-vs-polling-the-analytics-api)
- [The Events You'll Actually Receive](#the-events-youll-actually-receive)
- [Anatomy of a Webhook Payload](#anatomy-of-a-webhook-payload)
- [Verifying HMAC Signatures (with Working Code)](#verifying-hmac-signatures-with-working-code)
- [Retries, Idempotency, and Why Both Matter](#retries-idempotency-and-why-both-matter)
- [What to Look For in a Webhook Provider](#what-to-look-for-in-a-webhook-provider)
- [Setting Up Link Tracking Webhooks on U2L AI](#setting-up-link-tracking-webhooks-on-u2l-ai)
- [Production Pitfalls Nobody Warns You About](#production-pitfalls-nobody-warns-you-about)
- [Frequently Asked Questions](#frequently-asked-questions)

## What Is a Link Tracking Webhook?

<!-- DEFINED_TERM: Link Tracking Webhook -->
A **link tracking webhook** is an HTTPS endpoint that a URL shortener POSTs to whenever a tracked event happens on one of your short links. The payload is a small JSON body describing the event (what happened, when, which link, which account), the request carries a signature header so the receiver can verify it, and the shortener retries transient failures until the delivery succeeds or the retries run out. The whole point is to flip the integration from "ask every few minutes" to "we'll call you."
<!-- DEFINED_TERM_END -->

The mental model is identical to a Stripe or GitHub webhook. You own the receiver. The sender is some external service. The channel is a plain HTTP POST with a JSON body and a signature header. There is nothing magic about it, which is good news, because the trickiest part of a webhook integration is almost always on the receiver side, not the sender side. Signature verification, retry handling, and duplicate suppression are the three things that will trip up every first-time webhook consumer regardless of provider.

For a broader picture of how shorteners expose programmatic access generally, our [developer's guide to URL shortener APIs](/blog/url-shortener-api-guide) walks through the REST surface that webhooks live alongside, and our [complete link tracking guide](/blog/link-tracking-guide) covers how webhook data fits into a full attribution pipeline.

## Webhooks vs Polling the Analytics API

The direct answer: webhooks win for anything event-driven, and polling wins for anything report-driven. Confusing the two is the single most common mistake in integration design.

Polling the analytics API is the right pattern when you want aggregated numbers at a time granularity you choose. "Give me the click count for every link in the Spring Launch folder, grouped by day, for the last 30 days." That is a report. It makes no sense to receive 50,000 webhook events to answer that question. You GET the analytics endpoint once, you parse the response, you render the chart.

Webhooks are the right pattern when something has to react immediately. The user just created a link, so now your CRM needs a row. The link just got updated, so now your audit log needs an entry. A click just came in from a specific campaign, so now your sales team should get a Slack ping. These are events, not reports. Any attempt to poll your way into real-time responsiveness becomes an arms race against your rate limit, and the shortener will win.

A practical rule: if the thing on the other end is a dashboard, poll. If it's a workflow, webhook. If both exist and you're not sure which, start with the webhook, because you can always derive a report from a stream but you cannot derive a stream from a report.

## The Events You'll Actually Receive

Different providers emit different event families. The two most common patterns in 2026 are **lifecycle events** and **click events**, and some providers ship one, some ship both.

**Lifecycle events** fire when a link's state changes through the dashboard or API. The canonical names:

- `link.created` fires immediately after a new short link is written to the database.
- `link.updated` fires on any destination edit, tag change, folder move, or metadata patch.
- `link.deleted` fires when a link is removed from the account.

Lifecycle events are what you want for keeping a mirror of your link store in sync with another system, for triggering an audit log, or for firing a notification into Slack whenever a teammate ships a new campaign link. We emit all three, from the dashboard and the API alike, and delivery runs off a queue so the triggering request keeps its original latency. For details on how the API side of this looks, see our [URL shortener API guide](/blog/url-shortener-api-guide).

**Click events** fire whenever a visitor actually hits the redirect. The payload typically includes the timestamp, country, device, browser, OS, and referrer. Click webhooks are the real-time attribution feed, and they're what you want when a conversion workflow has to kick off within seconds of a click.

Click webhooks vary more between providers than lifecycle webhooks do. Some ship them as a separate "clickstream" product you have to enable, and payload fields differ, so check the provider's current docs before building against click events. For deep attribution patterns that use both webhooks and polling, our [marketing attribution guide](/blog/marketing-attribution-guide) and [conversion tracking guide](/blog/conversion-tracking-guide) walk through the full pipeline.

## Anatomy of a Webhook Payload

Every webhook you'll receive from a modern shortener looks roughly the same on the wire. The POST request has three parts worth caring about.

**The headers.** You get a `Content-Type: application/json`, a user agent identifying the sender, an event header naming the event type, and a signature header carrying both a timestamp and the HMAC digest. Our headers look like this:

```
X-U2L-Event: link.created
X-U2L-Signature: t=1761900000,v1=e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
```

The timestamp protects against replay attacks. If an attacker captures a valid webhook delivery and tries to replay it an hour later, your receiver should reject it on timestamp age before even checking the signature.

**The body.** A single JSON object describing the event. The shape is consistent across event types:

```json
{
  "id": "evt_4f1c9a2e7b6d4e0f8a3c5b9d2e1f7a6c",
  "event": "link.created",
  "createdAt": "2026-10-31T12:00:00.000Z",
  "data": {
    "id": "3f2b8c1e-9d4a-4e7b-a6c2-1b5d8e9f0a7c",
    "shortLink": "https://u2l.ai/launch",
    "domain": "u2l.ai",
    "slug": "launch",
    "destination": "https://example.com/launch",
    "title": "Spring launch",
    "tags": ["spring"],
    "permanent": true,
    "expiresAt": null,
    "folderId": null,
    "createdAt": "2026-10-31T12:00:00.000Z"
  }
}
```

The top-level `id` is a durable event ID (`data.id` is the link itself) that stays the same across retries of that delivery. Store it. It's what makes idempotency work (more on that below). A `link.deleted` event carries a slimmer `data` object with the link's `id`, `domain`, `slug`, and `type`.

**The response you send back.** A 2xx tells the sender you handled it. In our case, a redirect or a 4xx is a definitive failure and isn't retried, while a 5xx, a timeout, or a network error is transient and gets retried with growing delays. We make up to six attempts, with the gaps doubling from 30 seconds (30s, 60s, 120s, 240s, 480s), and an endpoint that keeps failing is disabled automatically. Schedules vary by provider, but the shape is usually similar.

## Verifying HMAC Signatures (with Working Code)

<!-- HOWTO_SCHEMA_START -->
<!-- HOWTO_NAME: How to Verify a Link Tracking Webhook Signature -->
<!-- HOWTO_DESCRIPTION: Step-by-step guide to safely verifying HMAC-SHA256 signatures on incoming link tracking webhooks. -->

### Step 1: Capture the raw request body before any parsing

Read the request body as raw bytes, not as a parsed JSON object. Re-serializing a parsed object changes whitespace, key order, or slash escaping, and the signature will fail to match. In Express, this means mounting a `raw` body parser on the webhook route specifically.

### Step 2: Extract the timestamp and signature from the header

The signature header is one line with comma-separated parts. Parse `t=` and `v1=` out of it. Reject the request immediately if either is missing.

### Step 3: Check the timestamp age before verifying

If the timestamp is older than roughly five minutes, reject the request as replay. Five minutes is the industry convention; longer windows weaken replay protection, shorter windows create false negatives when there's clock skew.

### Step 4: Recompute the HMAC-SHA256 digest

The digest is computed over `${timestamp}.${rawBody}` using your endpoint secret as the HMAC key. The output is hex-encoded.

### Step 5: Constant-time compare

Compare the recomputed digest against the one from the header using a constant-time comparison function, like Node's [`crypto.timingSafeEqual`](https://nodejs.org/api/crypto.html) or Python's [`hmac.compare_digest`](https://docs.python.org/3/library/hmac.html). A plain `===` leaks timing information that lets an attacker brute-force the signature byte by byte over many requests.

<!-- HOWTO_SCHEMA_END -->

Here is a working Node.js receiver using Express and the built-in `crypto` module:

```javascript
import crypto from "node:crypto";
import express from "express";

const app = express();
const SECRET = process.env.U2L_WEBHOOK_SECRET;
const TOLERANCE_SECONDS = 300;

app.post(
  "/webhooks/u2l",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const header = req.header("X-U2L-Signature") || "";
    const parts = Object.fromEntries(
      header.split(",").map((p) => p.split("=").map((s) => s.trim())),
    );
    const timestamp = Number(parts.t);
    const received = parts.v1;
    if (!timestamp || !received) return res.sendStatus(400);

    const age = Math.abs(Math.floor(Date.now() / 1000) - timestamp);
    if (age > TOLERANCE_SECONDS) return res.sendStatus(400);

    const expected = crypto
      .createHmac("sha256", SECRET)
      .update(`${timestamp}.${req.body.toString("utf8")}`)
      .digest("hex");

    const ok =
      received.length === expected.length &&
      crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));
    if (!ok) return res.sendStatus(401);

    const payload = JSON.parse(req.body.toString("utf8"));
    // Handle the event. Return 2xx fast; do heavy work in a background job.
    enqueueForProcessing(payload);
    res.sendStatus(200);
  },
);
```

And here is the same thing in Python with Flask and `hmac`:

```python
import hmac, hashlib, os, time, json
from flask import Flask, request, abort

app = Flask(__name__)
SECRET = os.environ["U2L_WEBHOOK_SECRET"].encode()
TOLERANCE_SECONDS = 300

@app.post("/webhooks/u2l")
def u2l_webhook():
    header = request.headers.get("X-U2L-Signature", "")
    parts = dict(p.strip().split("=", 1) for p in header.split(","))
    try:
        timestamp = int(parts["t"])
        received = parts["v1"]
    except (KeyError, ValueError):
        abort(400)

    if abs(int(time.time()) - timestamp) > TOLERANCE_SECONDS:
        abort(400)

    body = request.get_data()  # raw bytes, no parsing
    expected = hmac.new(
        SECRET, f"{timestamp}.".encode() + body, hashlib.sha256
    ).hexdigest()
    if not hmac.compare_digest(received, expected):
        abort(401)

    payload = json.loads(body)
    enqueue_for_processing(payload)
    return "", 200
```

Both snippets follow the same five rules: read raw body, parse the signature header, check timestamp age, recompute the [HMAC](https://en.wikipedia.org/wiki/HMAC), constant-time compare. If your verification code departs from this shape, something is probably off.

## Retries, Idempotency, and Why Both Matter

Here's the deal: webhooks will fire more than once. Not usually, but reliably often enough that you have to design for it. A network blip during your 200 response, a cold-start timeout, a receiver that happens to be mid-deploy; any of these cause the sender to retry a delivery you already processed. If your handler isn't idempotent, you'll create duplicate CRM rows, double-send Slack pings, and wake up to inexplicable analytics divergence between your dashboard and the shortener's.

The pattern that fixes this is small and boring. Store the event ID the sender gave you (the `id` field in the payload) in a dedup table with a TTL of a day or two. On each incoming webhook, look up the ID first. If it's there, return 200 immediately without re-processing. If not, insert it, then process, then respond. The whole dedup step takes a single Redis call or a single row insert against a unique index, so it adds basically zero latency.

The backoff schedule matters too, because if your receiver is down for ten minutes you want to understand what the sender will do. We make up to six attempts with doubling delays starting at 30 seconds, which means a failing endpoint gets its last retry roughly 16 minutes after the first. After that, the delivery is marked failed and the failure count on the endpoint goes up. Twenty consecutive definitive failures auto-disables the endpoint, which protects both sides from feedback loops. Other providers use different schedules; the shapes are all similar, the numbers vary.

One more thing: respond fast. Senders typically wait around 10 seconds (ours waits exactly 10), so if your handler does heavy work synchronously (writes to three databases, sends an email, calls another API) you'll hit the timeout and trigger a retry. The right pattern is to validate signature, dedupe, enqueue, and respond 200 in under a second. The actual work happens in a background job the response doesn't wait for.

## What to Look For in a Webhook Provider

A good link tracking webhook provider gets five things right: signed payloads, a timestamp you can check for replays, retries with backoff, stable event IDs, and protection against endpoints that fail forever. Anything less and you end up building those pieces yourself on the receiver side.

| Capability | Why it matters | U2L AI |
|---|---|---|
| **HMAC-SHA256 signing** | Proves the request came from the provider | **Yes** |
| **Signed timestamp** | Lets you reject replayed deliveries | **Yes** |
| **Retries with backoff** | Survives short receiver outages | **Yes, up to 6 attempts** |
| **Stable event ID** | Makes dedup and idempotency possible | **Yes** |
| **Auto-disable on repeated failure** | Stops runaway retries against a dead endpoint | **Yes** |
| **HTTPS-only endpoints** | Keeps payloads out of cleartext | **Yes** |
| **Queue-backed delivery** | Keeps link creation fast while events go out | **Yes** |

A few things worth calling out. HMAC signing with a timestamp replay guard is the pattern you want; if a provider only ships a static shared secret with no timestamp, you're responsible for building replay protection yourself. And check what a provider does with a 4xx: retrying a misconfigured endpoint for hours helps nobody, which is why we treat a 4xx as definitive.

We ship all seven of these for lifecycle events (`link.created`, `link.updated`, `link.deleted`). For click-level data, the pattern is to pair those webhooks with our analytics API, which returns clicks with geo, device, browser, OS, and referrer breakdowns. For a broader feature comparison that goes beyond webhooks, see our [URL shortener comparison table](/blog/url-shortener-comparison-table).

## Setting Up Link Tracking Webhooks on U2L AI

The setup takes about two minutes once you have an API key from your dashboard. Our [webhook docs](https://u2l.ai/developers/webhooks) cover every field.

**Create the endpoint via API.** POST a URL and an events array to `/api/v1/webhooks`:

```bash
curl -X POST "https://u2l.ai/api/v1/webhooks" \
  -H "Authorization: Bearer u2l_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.yourapp.com/webhooks/u2l",
    "events": ["link.created", "link.updated", "link.deleted"]
  }'
```

The response is the full endpoint object. Pay close attention to the `secret` field. **It is returned once, right now, and never again.** Store it in your secret manager immediately. If you lose it, delete the endpoint and create a new one to get a fresh secret.

**List, update, or delete endpoints.** The REST surface mirrors the links API. `GET /api/v1/webhooks` lists all endpoints on the account. `PATCH /api/v1/webhooks/:id` updates URL, events array, or active flag; setting `active: true` on a previously-disabled endpoint also resets its failure counter. `DELETE /api/v1/webhooks/:id` removes it. Each endpoint is scoped to the API key's account, so there's no cross-account access to worry about.

**Test the integration locally.** The one trick that most webhook integrations get wrong on day one is testing against a local receiver. The provider needs a publicly reachable HTTPS endpoint, which your laptop isn't. Use a tunneling tool to expose your dev server, then create a throwaway webhook pointing at the tunnel. Send a test link create through the dashboard, confirm your receiver gets the POST, verify the signature logic works, delete the test webhook. The entire loop takes five minutes if you've done it before, and it's the thing that catches the mistake before you ship.

For broader API context including authentication, rate limits, and endpoints, our [URL shortener API guide](/blog/url-shortener-api-guide) is the companion piece to this article. If you're deciding whether to track clicks via webhooks or UTMs, our [how to track link clicks guide](/blog/how-to-track-link-clicks) covers the three-method breakdown.

## Production Pitfalls Nobody Warns You About

Six things that only bite once you're a week into production.

**Receiver timeouts.** The sender has a short timeout (around 10 seconds). Your handler must respond in under a second, with the actual processing happening in a background job. If you call another API synchronously inside your webhook handler, you'll trigger retries whenever that other API is slow.

**Signature verification against the parsed body.** The signature is computed over the raw bytes. If you re-serialize a parsed JSON object before verifying, whitespace and key-ordering differences will make the signature fail. Keep the raw body around until after verification succeeds.

**Replay attacks via captured requests.** If an attacker captures a valid webhook delivery over your network, they can replay it against your endpoint indefinitely. The timestamp inside the signature header is what stops this. Reject anything older than your tolerance window (five minutes is standard) before checking the signature.

**Clock skew between sender and receiver.** Even a well-synchronized server can drift a few seconds. A tolerance window shorter than 30 seconds will produce false rejections. Five minutes is the industry convention for a reason.

**Dedup table bloat.** If you store every event ID forever, the dedup table grows without bound. Set a TTL that comfortably exceeds the sender's maximum retry window; a day or two is plenty.

**Silent endpoint auto-disable.** Most providers (us included) disable endpoints after too many consecutive failures. If your receiver is down for a maintenance window longer than the backoff schedule, you'll wake up to a disabled endpoint and no webhooks firing. Health-check the endpoint from a monitor outside your main app and re-enable it from the API when needed.

## Frequently Asked Questions

### What's the difference between a link tracking webhook and a click event webhook?
A link tracking webhook is the general category that includes everything a shortener might call you about. A click event webhook is specifically the type that fires on every visitor click. Lifecycle webhooks (`link.created`, `link.updated`, `link.deleted`) are the other main family; they fire on dashboard or API changes, not on visitor clicks. Some providers ship both families, some only ship one.

### Do all URL shorteners support webhooks?
No. Support varies a lot: some shorteners have no webhooks at all, and others reserve them for enterprise contracts. U2L AI ships signed lifecycle webhooks with retries, replay protection, and auto-disable. If webhooks are a requirement, confirm support against the provider's current docs before signing anything.

### How do I verify an HMAC-SHA256 signature?
Read the request body as raw bytes. Extract the timestamp and signature from the signature header. Check the timestamp isn't older than your tolerance window. Recompute HMAC-SHA256 over `${timestamp}.${rawBody}` using your endpoint secret. Compare the computed digest to the one from the header using a constant-time function like `crypto.timingSafeEqual` in Node.js or `hmac.compare_digest` in Python. Working code is in the verification section above.

### What happens if my webhook endpoint goes down?
The sender retries on a backoff schedule. We make six attempts with delays doubling from 30 seconds, so the last retry lands about 16 minutes after the first. After 20 consecutive failed deliveries, the endpoint is automatically disabled to prevent runaway retries. You can re-enable it through the API once your receiver is healthy.

### Can I use webhooks for real-time click tracking on U2L AI?
Our webhook events cover the link lifecycle (`link.created`, `link.updated`, `link.deleted`). For click data, pair those webhooks with the analytics API, which returns clicks with geo, device, browser, OS, and referrer breakdowns. That combination covers most click-driven workflows.

### How do I prevent duplicate processing from webhook retries?
Store the event ID (the `id` field in the payload) in a dedup table with a TTL of a day or two. On every incoming webhook, look up the ID. If it exists, return 200 immediately without re-processing. If not, insert it with a unique constraint, then process the event. This pattern makes your handler safely idempotent even when the sender retries.

### Can I use HTTP (not HTTPS) for the receiver URL?
No. Reputable providers reject non-HTTPS webhook URLs at creation, and our API returns a validation error if the URL isn't https. This isn't optional; signature verification doesn't protect you from passive network observers if the payload itself is in cleartext.

### What's a good test harness for webhook integrations?
Expose your local dev server via a tunneling tool, create a disposable webhook endpoint pointing at the tunnel URL, trigger events through the dashboard or API, confirm your receiver gets the POST, verify the signature logic works end to end, delete the test endpoint when you're done. This loop takes five minutes and catches more real bugs than any amount of unit testing against a mocked sender.

## From Polling to Push

Webhooks turn link tracking from a report you fetch into a stream you react to. Once you've got signature verification right, dedup on the event ID, a fast 200-response handler, and background processing for the heavy work, you have an integration that scales from your first ten events to your millionth without the shape of the code changing. [Create your U2L AI account](https://u2l.ai/app/signup), generate an API key, register your endpoint, and your first signed delivery will land before your coffee goes cold. The full feature list is on [u2l.ai/features](https://u2l.ai/features).
