feat: Webhooks for Real-Time Click Events

app/api/links/click/route.ts

@@ -5,6 +5,9 @@ import { getForwardedIp } from "@/lib/analyticsUtils";
 import { checkRateLimit } from "@/lib/rateLimit";
 import { resolveUserByUsername } from "@/lib/userLookup";
 
+import crypto from "crypto";
+import { enqueueJob } from "@/lib/jobs";
+
 // 30 requests per minute per IP on the click endpoint.
 const CLICK_RATE_LIMIT = 30;
 const CLICK_RATE_WINDOW_MS = 60 * 1000;
@@ -35,7 +38,16 @@ export async function POST(req: Request) {
 
     const link = await prisma.link.findFirst({
         where: { platform, workspaceId: resolved.user.id, isPublic: true },
-        select: { id: true, workspaceId: true },
+        select: { 
+            id: true, 
+            workspaceId: true,
+            workspace: {
+                select: {
+                    webhookUrl: true,
+                    webhookSecret: true
+                }
+            }
+        },
     });
 
     if (!link) {
@@ -48,5 +60,25 @@ export async function POST(req: Request) {
         headers: req.headers,
     });
 
+    if (link.workspace.webhookUrl && link.workspace.webhookSecret) {
+        const payload = JSON.stringify({
+            linkId: link.id,
+            platform,
+            timestamp: new Date().toISOString()
+        });
+
+        const signature = crypto
+            .createHmac("sha256", link.workspace.webhookSecret)
+            .update(payload)
+            .digest("hex");
+
+        // Enqueue a durable delivery job instead of fire-and-forget fetch
+        await enqueueJob("webhook-dispatch", {
+            url: link.workspace.webhookUrl,
+            signature,
+            payload: JSON.parse(payload)
+        });
+    }
+
     return NextResponse.json({ success: true });
 }

app/api/settings/route.ts

@@ -4,6 +4,8 @@ import { getServerSession } from "next-auth";
 import { authOptions } from "@/lib/auth";
 import { resolveActiveWorkspace } from "@/lib/workspace";
 import { invalidateProfileCache } from "@/lib/profileCache";
+import crypto from "crypto";
+import { validateWebhookUrl, WebhookValidationError } from "@/lib/ssrf";
 
 export async function PUT(req: NextRequest) {
   try {
@@ -12,30 +14,63 @@ export async function PUT(req: NextRequest) {
       return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
     }
     const body = await req.json();
-    const { enableEmailCapture, workspaceId: bodyWorkspaceId } = body;
+    const { enableEmailCapture, workspaceId: bodyWorkspaceId, webhookUrl } = body;
 
     const preferredWorkspaceId = req.headers.get("x-workspace-id") || req.nextUrl?.searchParams?.get("workspaceId") || bodyWorkspaceId;
     const workspace = await resolveActiveWorkspace(session.user.id, preferredWorkspaceId);
     if (!workspace) {
       return NextResponse.json({ error: "Workspace not found" }, { status: 404 });
     }
 
-    if (typeof enableEmailCapture !== "boolean") {
-      return NextResponse.json({ error: "enableEmailCapture must be a boolean" }, { status: 400 });
+    if (webhookUrl !== undefined && workspace.role !== "OWNER") {
+      return NextResponse.json({ error: "Only workspace owners can configure webhooks" }, { status: 403 });
+    }
+
+    const updateData: { enableEmailCapture?: boolean; webhookUrl?: string | null; webhookSecret?: string | null } = {};
+    if (enableEmailCapture !== undefined) {
+      if (typeof enableEmailCapture !== "boolean") {
+        return NextResponse.json({ error: "enableEmailCapture must be a boolean" }, { status: 400 });
+      }
+      updateData.enableEmailCapture = enableEmailCapture;
+    }
+
+    if (webhookUrl !== undefined) {
+      if (webhookUrl === "") {
+        updateData.webhookUrl = null;
+        updateData.webhookSecret = null;
+      } else {
+        await validateWebhookUrl(webhookUrl);
+        updateData.webhookUrl = webhookUrl;
+
+        const existingWorkspace = await prisma.workspace.findUnique({ where: { id: workspace.id }, select: { webhookSecret: true }});
+        if (!existingWorkspace?.webhookSecret) {
+          updateData.webhookSecret = crypto.randomBytes(32).toString('hex');
+        }
+      }
     }
 
     const updatedWorkspace = await prisma.workspace.update({
       where: { id: workspace.id },
-      data: { enableEmailCapture },
+      data: updateData,
     });
 
     // enableEmailCapture renders on the public profile — purge the cache.
-    await invalidateProfileCache(workspace.id);
+    if (enableEmailCapture !== undefined) {
+      await invalidateProfileCache(workspace.id);
+    }
 
-    return NextResponse.json({ success: true, enableEmailCapture: updatedWorkspace.enableEmailCapture }, { status: 200 });
+    return NextResponse.json({ 
+      success: true, 
+      enableEmailCapture: updatedWorkspace.enableEmailCapture,
+      webhookUrl: updatedWorkspace.webhookUrl,
+      webhookSecret: updatedWorkspace.webhookSecret 
+    }, { status: 200 });
 
   } catch (error) {
     console.error("Settings update error:", error);
+    if (error instanceof WebhookValidationError) {
+        return NextResponse.json({ error: error.message }, { status: 400 });
+    }
     return NextResponse.json({ error: "Internal server error" }, { status: 500 });
   }
 }

app/dashboard/DashboardClient.tsx

@@ -14,6 +14,7 @@ import { AppearanceSection } from "./AppearanceSection";
 import { SeoSection } from "./SeoSection";
 import { LayoutStyle } from "@/app/[username]/types/type";
 import { LivePreview } from "@/components/dashboard/LivePreview";
+import { WebhookSection } from "./WebhookSection";
 
 export default function DashboardClient({
     userId,
@@ -35,6 +36,8 @@ export default function DashboardClient({
     initialThemeType,
     initialThemeColor,
     initialThemeCustom,
+    initialWebhookUrl,
+    initialWebhookSecret,
 }: {
     userId?: string;
     workspaceId: string;
@@ -55,7 +58,11 @@ export default function DashboardClient({
     initialThemeType?: string;
     initialThemeColor?: string;
     initialThemeCustom?: string | null;
+    initialWebhookUrl?: string | null;
+    initialWebhookSecret?: string | null;
 }) {
+    const [webhookUrl, setWebhookUrl] = useState(initialWebhookUrl ?? null);
+    const [webhookSecret, setWebhookSecret] = useState(initialWebhookSecret ?? null);
     const router = useRouter();
     const [links, setLinks] = useState(initialLinks);
 
@@ -87,7 +94,7 @@ export default function DashboardClient({
     const [backgroundImage, setBackgroundImage] = useState<string | null>(initialBackgroundImage || "");
     const [seoTitle, setSeoTitle] = useState(initialSeoTitle || "");
     const [seoDescription, setSeoDescription] = useState(initialSeoDescription || "");
-    const [activeTab, setActiveTab] = useState<"links" | "appearance" | "seo">("links");
+    const [activeTab, setActiveTab] = useState<"links" | "appearance" | "seo" | "webhooks">("links");
     const [showAdd, setShowAdd] = useState(false);
     const [showGroupAdd, setShowGroupAdd] = useState(false);
     const [isEmailCaptureEnabled, setIsEmailCaptureEnabled] = useState(enableEmailCapture ?? false);
@@ -390,6 +397,12 @@ export default function DashboardClient({
                     >
                         SEO
                     </button>
+                    <button 
+                        className={`pb-2 px-1 text-sm font-medium ${activeTab === 'webhooks' ? 'border-b-2 border-primary text-foreground' : 'text-muted-foreground'}`}
+                        onClick={() => setActiveTab('webhooks')}
+                    >
+                        Webhooks
+                    </button>
                 </div>
 
                 {activeTab === 'links' ? (
@@ -467,7 +480,7 @@ export default function DashboardClient({
                         onUpdateLayout={setLayoutStyle}
                         onUpdateBackgroundImage={setBackgroundImage}
                     />
-                ) : (
+                ) : activeTab === 'seo' ? (
                     <SeoSection 
                         workspaceId={workspaceId}
                         initialTitle={seoTitle}
@@ -477,6 +490,16 @@ export default function DashboardClient({
                             setSeoDescription(desc);
                         }}
                     />
+                ) : (
+                    <WebhookSection
+                        workspaceId={workspaceId}
+                        initialWebhookUrl={webhookUrl}
+                        initialWebhookSecret={webhookSecret}
+                        onUpdate={(url, secret) => {
+                            setWebhookUrl(url);
+                            setWebhookSecret(secret);
+                        }}
+                    />
                 )}
 
                         <footer className="pt-10 border-t text-center text-sm text-muted-foreground">

app/dashboard/WebhookSection.tsx

@@ -0,0 +1,80 @@
+import { useState } from "react";
+import toast from "react-hot-toast";
+
+interface WebhookSectionProps {
+    workspaceId: string;
+    initialWebhookUrl?: string | null;
+    initialWebhookSecret?: string | null;
+    onUpdate?: (url: string | null, secret: string | null) => void;
+}
+
+export function WebhookSection({ workspaceId, initialWebhookUrl, initialWebhookSecret, onUpdate }: WebhookSectionProps) {
+    const [webhookUrl, setWebhookUrl] = useState(initialWebhookUrl || "");
+    const [secret, setSecret] = useState(initialWebhookSecret || "");
+    const [saving, setSaving] = useState(false);
+
+    const handleSave = async () => {
+        setSaving(true);
+        try {
+            const res = await fetch("/api/settings", {
+                method: "PUT",
+                headers: { 
+                    "Content-Type": "application/json",
+                    "x-workspace-id": workspaceId
+                },
+                body: JSON.stringify({ webhookUrl: webhookUrl.trim() === "" ? "" : webhookUrl }),
+            });
+            const data = await res.json();
+            if (data.success) {
+                toast.success("Webhook settings saved!");
+                setSecret(data.webhookSecret || "");
+                if (onUpdate) onUpdate(data.webhookUrl, data.webhookSecret);
+            } else {
+                toast.error(data.error || "Failed to save webhook settings");
+            }
+        } catch (error) {
+            toast.error("Failed to save webhook settings");
+        }
+        setSaving(false);
+    };
+
+    return (
+        <div className="bg-card text-card-foreground p-6 rounded-lg border border-border shadow-sm">
+            <h2 className="text-xl font-semibold mb-4">Developer Webhooks</h2>
+            <p className="text-sm text-muted-foreground mb-6">
+                Receive real-time HTTP POST requests whenever a visitor clicks a link on your profile.
+            </p>
+            <div className="space-y-4">
+                <div>
+                    <label className="block text-sm font-medium mb-1">Payload URL</label>
+                    <input 
+                        type="url" 
+                        value={webhookUrl}
+                        onChange={(e) => setWebhookUrl(e.target.value)}
+                        placeholder="https://example.com/webhook"
+                        className="w-full px-3 py-2 border rounded-md bg-background focus:outline-none focus:ring-2 focus:ring-primary"
+                    />
+                </div>
+                {secret && (
+                    <div>
+                        <label className="block text-sm font-medium mb-1">Signing Secret</label>
+                        <input 
+                            type="text" 
+                            readOnly
+                            value={secret}
+                            className="w-full px-3 py-2 border rounded-md bg-muted text-muted-foreground font-mono text-sm"
+                        />
+                        <p className="text-xs text-muted-foreground mt-1">Use this secret to verify the HMAC SHA256 signature in the x-linkid-signature header.</p>
+                    </div>
+                )}
+                <button 
+                    onClick={handleSave}
+                    disabled={saving}
+                    className="px-4 py-2 bg-primary text-primary-foreground rounded-md text-sm font-medium hover:bg-primary/90 disabled:opacity-50"
+                >
+                    {saving ? "Saving..." : "Save Webhook"}
+                </button>
+            </div>
+        </div>
+    );
+}

app/dashboard/page.tsx

@@ -66,6 +66,8 @@ export default async function DashboardPage() {
             initialThemeType={workspace.profileDraft?.themeType ?? workspace.themeType}
             initialThemeColor={workspace.profileDraft?.themeColor ?? workspace.themeColor}
             initialThemeCustom={workspace.profileDraft?.themeCustom ?? workspace.themeCustom}
+            initialWebhookUrl={activeWorkspace.role === 'OWNER' ? workspace.webhookUrl : undefined}
+            initialWebhookSecret={activeWorkspace.role === 'OWNER' ? workspace.webhookSecret : undefined}
         />
     );
 }

lib/ssrf.ts

@@ -0,0 +1,69 @@
+import dns from 'dns/promises';
+import ipaddr from 'ipaddr.js';
+
+export class WebhookValidationError extends Error {
+    constructor(message: string) {
+        super(message);
+        this.name = 'WebhookValidationError';
+    }
+}
+
+export async function validateWebhookUrl(urlString: string): Promise<void> {
+    let url: URL;
+    try {
+        url = new URL(urlString);
+    } catch {
+        throw new WebhookValidationError('Invalid URL format');
+    }
+
+    if (url.protocol !== 'https:') {
+        throw new WebhookValidationError('Webhook URLs must use HTTPS');
+    }
+
+    // Resolve the hostname
+    let addresses: { address: string; family: number }[] = [];
+    try {
+        addresses = await dns.lookup(url.hostname, { all: true });
+    } catch (error) {
+        throw new WebhookValidationError(`Could not resolve hostname: ${url.hostname}`);
+    }
+
+    if (addresses.length === 0) {
+        throw new WebhookValidationError(`Could not resolve hostname: ${url.hostname}`);
+    }
+
+    for (const { address } of addresses) {
+        if (!ipaddr.isValid(address)) {
+            throw new WebhookValidationError(`Invalid IP address resolved: ${address}`);
+        }
+
+        const ip = ipaddr.parse(address);
+        const range = ip.range();
+
+        // Block all non-unicast or private ranges
+        const blockedRanges = [
+            'unspecified',
+            'broadcast',
+            'multicast',
+            'linkLocal',
+            'loopback',
+            'private',
+            'carrierGradeNat',
+            'uniqueLocal',
+            'ipv4Mapped',
+            'rfc6145',
+            'rfc6052',
+            '6to4',
+            'teredo'
+        ];
+
+        if (blockedRanges.includes(range)) {
+            throw new WebhookValidationError(`Resolved IP address (${address}) is in a blocked range (${range})`);
+        }
+
+        // Specifically block AWS IMDS IPv4 (169.254.169.254) which might be covered by linkLocal
+        if (address === '169.254.169.254') {
+            throw new WebhookValidationError('Metadata service IP addresses are not allowed');
+        }
+    }
+}