Webhooks & Real-Time Events API

Subscribe to real-time event streams, receive instant HTTP notifications, and verify HMAC-SHA256 signatures.

4 min read•Official Edge Documentation

Overview & Architecture

LShorter webhooks notify your backend systems in real time whenever an event occurs on your short links (click registered, conversion recorded, quota reached, link expired).

All outgoing HTTP POST payloads are cryptographically signed with an HMAC-SHA256 secret key via the x-lshorter-signature header to guarantee authenticity and prevent tampering.

Pour des raisons de sécurité et d'intégrité, la création et la configuration des webhooks s'effectuent exclusivement depuis le tableau de bord web LShorter (Paramètres > Webhooks). L'API et le SDK vous permettent de lister vos abonnements actifs et de traiter les événements entrants.

Key Principles

Core architectural pillars ensuring high performance, isolation, and security.

01Supported Event Types

link.clicked, link.converted, link.limit_reached, link.expired, link.created, link.deleted.

02Cryptographic HMAC-SHA256 Signatures

Validate the x-lshorter-signature header to verify payload integrity before processing.

03Configuration via Tableau de Bord

Enregistrement sécurisé des endpoints d'écoute directement depuis l'interface Paramètres > Webhooks.

04Exponential Backoff Retries

Automatic retry schedule with exponential backoff if your webhook receiver returns a 5xx error or times out.

SDK Integration

Implementation & SDK Examples

Ready-to-use TypeScript code snippets and configuration examples for your integrations.

1. Verifying HMAC Signatures in Next.js / Node.js

Cryptographically verify incoming webhook payloads before processing:

app/api/webhooks/lshorter/route.ts

typescript

123456789101112131415161718192021222324252627282930313233343536
import { NextRequest, NextResponse } from "next/server";
import crypto from "node:crypto";
 
const WEBHOOK_SECRET = process.env.LSHORTER_WEBHOOK_SECRET!;
 
export async function POST(req: NextRequest) {
  const rawBody = await req.text();
  const signature = req.headers.get("x-lshorter-signature");
 
  // 1. Verify HMAC-SHA256 signature
  const expectedSig = crypto
    .createHmac("sha256", WEBHOOK_SECRET)
    .update(rawBody)
    .digest("hex");
 
  if (signature !== expectedSig) {
    return NextResponse.json({ error: "Invalid cryptographic signature" }, { status: 401 });
  }
 
  // 2. Process event
  const event = JSON.parse(rawBody);
 
  switch (event.type) {
    case "link.clicked":
      console.log(`Click registered on ${event.data.slug} from ${event.data.country}`);
      break;
    case "link.converted":
      console.log(`Conversion of ${event.data.amount} ${event.data.currency} attributed!`);
      break;
    case "link.limit_reached":
      console.warn(`Click limit reached for link ${event.data.slug}`);
      break;
  }
 
  return NextResponse.json({ received: true });
}

REST API Specification

API Endpoints & Reference

Direct HTTP request methods, parameters schema, authentication, and responses.

GET

List Webhook Subscriptions

Bearer <API_KEY>60 to 1,400 req/min (by plan)

https://lsho.cc/api/v1/webhooks

Retrieves all active webhook subscriptions configured for your account. (Note: New webhooks must be registered securely from the LShorter Web Dashboard in Settings > Webhooks).

Request Examples

bash

12
curl -X GET "https://lsho.cc/api/v1/webhooks" \
  -H "Authorization: Bearer $LSHORTER_API_KEY"

Response Payload

200 OKList of registered webhook endpoints and their subscribed events.

response-200.json

json

1234567891011
{
  "webhooks": [
    {
      "id": "wh_883019283",
      "url": "https://api.my-domain.com/webhooks/lshorter",
      "events": ["link.clicked", "link.converted", "link.limit_reached"],
      "isActive": true,
      "createdAt": "2026-09-17T12:30:00.000Z"
    }
  ]
}

Webhook Payload Example

JSON payload dispatched on a link.clicked or link.converted event:

response.json

json

1234567891011121314
{
  "id": "evt_883019283",
  "type": "link.clicked",
  "createdAt": "2026-09-17T12:35:00.000Z",
  "data": {
    "linkId": "link_89f023ab912",
    "slug": "guide-2026",
    "country": "US",
    "device": "desktop",
    "browser": "Chrome",
    "ipMasked": "82.64.***.***",
    "timestamp": 1789244534000
  }
}

Recommended Best Practices

Expert tips to maximize performance, resilience, and link security.

Recommendation 01

Respond quickly with an HTTP 200 OK (within 3,000ms) and offload lengthy business tasks to background queues (BullMQ, Celery, SQS).

Recommendation 02

Always verify the HMAC-SHA256 signature before parsing or acting upon webhook JSON data.

Recommendation 03

Store received event.id tokens to build idempotent event handlers that safely handle network retries.

Previous guideDynamic QR Code Generation API Next guideConversion Tracking & Financial Metrics (Amount & Count)

Related Guides & APIs

Overview & Architecture

LShorter webhooks notify your backend systems in real time whenever an event occurs on your short links (click registered, conversion recorded, quota reached, link expired).

All outgoing HTTP POST payloads are cryptographically signed with an HMAC-SHA256 secret key via the x-lshorter-signature header to guarantee authenticity and prevent tampering.

123456789101112131415161718192021222324252627282930313233343536

import { NextRequest, NextResponse } from "next/server"; import crypto from "node:crypto"; const WEBHOOK_SECRET = process.env.LSHORTER_WEBHOOK_SECRET!; export async function POST(req: NextRequest) { const rawBody = await req.text(); const signature = req.headers.get("x-lshorter-signature"); // 1. Verify HMAC-SHA256 signature const expectedSig = crypto .createHmac("sha256", WEBHOOK_SECRET) .update(rawBody) .digest("hex"); if (signature !== expectedSig) { return NextResponse.json({ error: "Invalid cryptographic signature" }, { status: 401 }); } // 2. Process event const event = JSON.parse(rawBody); switch (event.type) { case "link.clicked": console.log(`Click registered on ${event.data.slug} from ${event.data.country}`); break; case "link.converted": console.log(`Conversion of ${event.data.amount} ${event.data.currency} attributed!`); break; case "link.limit_reached": console.warn(`Click limit reached for link ${event.data.slug}`); break; } return NextResponse.json({ received: true }); }

1234567891011

{ "webhooks": [ { "id": "wh_883019283", "url": "https://api.my-domain.com/webhooks/lshorter", "events": ["link.clicked", "link.converted", "link.limit_reached"], "isActive": true, "createdAt": "2026-09-17T12:30:00.000Z" } ] }

Webhook Payload Example

JSON payload dispatched on a link.clicked or link.converted event:

response.json

json

1234567891011121314
{
  "id": "evt_883019283",
  "type": "link.clicked",
  "createdAt": "2026-09-17T12:35:00.000Z",
  "data": {
    "linkId": "link_89f023ab912",
    "slug": "guide-2026",
    "country": "US",
    "device": "desktop",
    "browser": "Chrome",
    "ipMasked": "82.64.***.***",
    "timestamp": 1789244534000
  }
}