Linktree webhooks events

Linktree Webhooks & Events

Overview

Linktree emits real-time webhook events whenever links, profiles, or analytics milestones change. These events enable automations such as syncing new bio links to a CMS, triggering social media posts when a profile is updated, alerting marketing teams when traffic milestones are hit, and auditing link lifecycle changes for compliance dashboards. All payloads are JSON over HTTPS with HMAC-SHA256 signature verification to guarantee authenticity.

Prerequisites

• A registered Linktree developer app with webhook permissions enabled
• Webhook endpoint URL accessible over HTTPS (TLS 1.2+)
• Signing secret from the Linktree developer dashboard (LINKTREE_WEBHOOK_SECRET)
• Express.js with raw body parsing enabled for signature verification

Webhook Registration

import axios from "axios";

const res = await axios.post(
  "https://api.linktr.ee/v1/webhooks",
  {
    url: "https://your-app.com/webhooks/linktree",
    events: ["link.created", "link.updated", "link.deleted",
             "profile.updated", "analytics.milestone"],
  },
  { headers: { Authorization: `Bearer ${process.env.LINKTREE_API_TOKEN}` } }
);
console.log("Subscription ID:", res.data.id);

Signature Verification

import crypto from "crypto";
import { Request, Response, NextFunction } from "express";

function verifyLinktreeSignature(req: Request, res: Response, next: NextFunction) {
  const signature = req.headers["x-linktree-signature"] as string;
  const timestamp = req.headers["x-linktree-timestamp"] as string;
  if (!signature || !timestamp) return res.status(401).send("Missing signature");

  const payload = `${timestamp}.${(req as any).rawBody}`;
  const expected = crypto
    .createHmac("sha256", process.env.LINKTREE_WEBHOOK_SECRET!)
    .update(payload)
    .digest("hex");

  if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
    return res.status(403).send("Invalid signature");
  }
  next();
}

Event Handler

app.post("/webhooks/linktree", verifyLinktreeSignature, (req, res) => {
  const { type, data, timestamp } = req.body;

  switch (type) {
    case "link.created":
      console.log(`New link: ${data.title} → ${data.url}`);
      break;
    case "link.updated":
      console.log(`Link edited: ${data.link_id}, position: ${data.position}`);
      break;
    case "link.deleted":
      console.log(`Link removed: ${data.link_id}`);
      break;
    case "profile.updated":
      console.log(`Profile changed: bio=${data.bio}, avatar=${data.avatar_url}`);
      break;
    case "analytics.milestone":
      console.log(`Milestone: ${data.metric} hit ${data.threshold} on ${data.link_id}`);
      break;
    default:
      console.warn(`Unhandled event: ${type}`);
  }
  res.status(200).json({ received: true });
});

Event Types

Event	Payload Fields	Use Case
link.created	link_id, title, url, position	Sync new links to CMS or dashboard
link.updated	link_id, title, url, position, thumbnail_url	Detect reordering or URL changes
link.deleted	link_id, deleted_at	Clean up external references
profile.updated	username, bio, avatar_url, theme	Mirror profile changes to marketing sites
analytics.milestone	link_id, metric, value, threshold	Alert when a link hits click milestones

Retry & Idempotency

const processed = new Set<string>();

function ensureIdempotent(req: Request, res: Response, next: NextFunction) {
  const deliveryId = req.headers["x-linktree-delivery-id"] as string;
  if (processed.has(deliveryId)) {
    return res.status(200).json({ duplicate: true });
  }
  processed.add(deliveryId);
  next();
}
// Linktree retries up to 5 times with exponential backoff (10s, 30s, 90s, 270s, 810s).
// Webhooks are disabled after 72 hours of consecutive failures.

Error Handling

Issue	Cause	Fix
401 on every delivery	Signing secret rotated in dashboard	Re-copy secret and redeploy
Duplicate events processed	Retry after timeout	Implement idempotency check on x-linktree-delivery-id
Missing analytics.milestone events	Milestone thresholds not configured	Set thresholds in Linktree dashboard under Analytics
Payload body is empty	Body parser consuming raw body	Use express.raw({ type: "application/json" }) before route
Webhook auto-disabled	Endpoint returned 5xx for 72 hours	Fix endpoint, then re-enable subscription via API

Resources

• Linktree Developer Platform

Next Steps

See linktree-security-basics.