Quick Start Guide

Get Linkbay integrated into your merchant site in just a few steps.

Prerequisites

A Linkbay merchant account
An API key (get one from your dashboard)
A webhook endpoint on your server (HTTPS required)

Step 1: Configure Your Webhook

Go to your Merchant Dashboard
Click "Add Webhook"
Enter your endpoint URL (e.g., https://yoursite.com/api/linkbay-webhook)
Copy your webhook secret - you'll need this for signature verification

Step 2: Create Your Webhook Handler

Create an endpoint to receive click notifications. Here's a minimal example:

Next.js / Node.js

app/api/linkbay-webhook/route.ts

import crypto from 'crypto';

// In-memory store (use Redis/database in production)
const clickStore = new Map();

export async function POST(request: Request) {
  const signature = request.headers.get('X-Linkbay-Signature');
  const payload = await request.text();

  // Verify signature
  const expected = 'sha256=' + crypto
    .createHmac('sha256', process.env.LINKBAY_WEBHOOK_SECRET!)
    .update(payload)
    .digest('hex');

  if (signature !== expected) {
    return Response.json({ error: 'Invalid signature' }, { status: 401 });
  }

  const data = JSON.parse(payload);

  // Store the click for later verification
  clickStore.set(data.click_id, {
    expectedTag: data.expected_tag,
    creatorId: data.creator_id,
    timestamp: Date.now(),
  });

  return Response.json({ received: true });
}

// Export for use at checkout
export function getStoredClick(clickId: string) {
  return clickStore.get(clickId);
}

Step 3: Verify at Checkout

When a user reaches checkout, compare the arrived tag with the expected tag:

// At checkout
async function processCheckout(order: Order) {
  const urlParams = new URLSearchParams(window.location.search);
  const clickId = urlParams.get('lb_click');
  const arrivedTag = urlParams.get('tag');

  if (!clickId) {
    // No Linkbay click - process normally
    return processNormalCheckout(order, arrivedTag);
  }

  // Option 1: Check stored webhook data
  const stored = getStoredClick(clickId);

  // Option 2: Or call the API directly
  const response = await fetch(
    `/api/verify-click?click_id=${clickId}&arrived_tag=${arrivedTag}`
  );
  const result = await response.json();

  if (result.isHijacked) {
    // Credit the real creator!
    console.log(`Hijack detected. Crediting ${result.expectedTag}`);
    return processCheckout(order, result.expectedTag);
  }

  return processCheckout(order, arrivedTag);
}

Step 4: Create a Verification API Route

Add a server-side route to call Linkbay's API (keeps your API key secure):

app/api/verify-click/route.ts

export async function GET(request: Request) {
  const { searchParams } = new URL(request.url);
  const clickId = searchParams.get('click_id');
  const arrivedTag = searchParams.get('arrived_tag');

  const response = await fetch(
    `https://api.linkbay.io/api/v1/merchant/lookup-click?click_id=${clickId}`,
    {
      headers: {
        'X-API-Key': process.env.LINKBAY_API_KEY!,
      },
    }
  );

  if (!response.ok) {
    return Response.json({ error: 'Click not found' }, { status: 404 });
  }

  const data = await response.json();
  const isHijacked = data.expectedTag !== arrivedTag;

  return Response.json({
    ...data,
    arrivedTag,
    isHijacked,
  });
}

Step 5: Test with Sandbox

Use our Sandbox Store to test your integration:

Set your webhook URL in the merchant dashboard
Create a test link pointing to sandbox.linkbay.io/product/test
Click the link and verify the webhook is received
Check the "Verify Click" button to see the comparison

Environment Variables

Add these to your .env.local:

.env.local

LINKBAY_API_KEY=your_api_key_here
LINKBAY_WEBHOOK_SECRET=your_webhook_secret_here

Next Steps

Read the Detecting Hijacks guide for advanced patterns
Review the API Reference for all endpoints
Set up proper storage (Redis/database) for production use