nLink

Developers

nLink API and webhooks

Create and manage links from your own app, pull click statistics, and receive click and link events in real time with webhooks. The API and webhooks are available on Gold and Enterprise plans.

Authentication and limits

Create your API key under Settings → API access. The key is shown once; we store only its hash. Send it with every request:

Authorization: Bearer nlk_xxxxxxxxxxxxxxxx
# ya da / or
X-API-Key: nlk_xxxxxxxxxxxxxxxx
  • Base URL: https://api.nlink.tr/api/v1
  • Rate limit: Gold 60/min, Enterprise 300/min. Responses carry X-RateLimit-Limit and X-RateLimit-Remaining; when exceeded you get 429 with Retry-After.
  • Your plan limits (monthly links) also apply to the API.
  • All bodies are JSON; times are ISO 8601 (UTC).

Endpoints

GET/api/v1/me

Account, plan, limits and this month's click usage.

curl https://api.nlink.tr/api/v1/me -H "Authorization: Bearer $NLINK_API_KEY"

POST/api/v1/links

Creates a link. The destination is safety-scanned; counts against your plan quota.

urlDestination URL (required, http/https).
slugCustom short name (optional). 409 slug_taken if in use.
domainnlink.tr or your configured custom domain (optional).
curl -X POST https://api.nlink.tr/api/v1/links \
  -H "Authorization: Bearer $NLINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/yaz-indirimi", "slug": "kampanya"}'
201 Created
{
  "id": "6702f1c4a9b3e1d2c3f4a5b6",
  "slug": "kampanya",
  "short_url": "https://nlink.tr/kampanya",
  "url": "https://example.com/yaz-indirimi",
  "domain": "nlink.tr",
  "created_at": "2026-10-03T12:00:00Z",
  "created_by": null,
  "clicks": 128,
  "last_click_at": "2026-10-04T08:15:02Z",
  "group_ids": []
}

Errors

Error responses always have the same shape:

{ "error": { "code": "slug_taken", "message": "Bu kısa ad kullanımda." } }
HTTPcodeMeaning
400invalid_slug · invalid_domainInvalid short name or domain.
401unauthorized · invalid_api_keyMissing or invalid key.
403plan_requiredAPI requires Gold or Enterprise.
404not_foundLink not found (or not yours).
409slug_taken · slug_reserved · slug_retiredShort name in use, reserved, or belonged to a deleted link (never reissued).
422invalid_url · unsafe_urlDestination invalid or blocked by the safety scan.
429rate_limited · quota_exceededPer-minute limit or plan quota reached.

Webhook

Add webhook endpoints under Settings → Webhook (up to 5, https only). When a selected event happens we send a signed POST request to your endpoint.

link.createdA link was created (dashboard, extension or API).
link.updatedThe destination or short name changed.
link.deletedA link was deleted.
link.clickedA human click (bots excluded; within your monthly click allowance). Includes country, city, device, source and campaign; no IP address is sent.
ping"Send test" from the dashboard.

Example request:

POST https://ornek.com/nlink-webhook
Content-Type: application/json
X-Nlink-Event: link.clicked
X-Nlink-Delivery: 6702f9a1c2d3e4f5a6b7c8d9
X-Nlink-Signature: t=1791047318,v1=5f2b…c91e

{
  "id": "6702f9a1c2d3e4f5a6b7c8d9",
  "event": "link.clicked",
  "created_at": "2026-10-04T08:15:02Z",
  "data": {
    "link": { "id": "6702f1c4…", "slug": "kampanya", "short_url": "https://nlink.tr/kampanya", "url": "https://example.com/yaz-indirimi" },
    "clicked_at": "2026-10-04T08:15:02Z",
    "country": "TR", "region": "İstanbul", "city": "Istanbul",
    "device": "mobile", "os": "iOS", "browser": "Mobile Safari",
    "referrer_host": "instagram.com", "app": "instagram", "campaign": "yaz",
    "unique": true
  }
}

Verifying the signature

v1 in the X-Nlink-Signature header is the HMAC-SHA256 of "<t>.<raw body>" with the webhook's signing secret (whsec_…). Verify the raw body before parsing it and reject requests whose timestamp t is older than 5 minutes (replay protection).

Node.js

import crypto from "node:crypto";

// rawBody: isteğin ham gövdesi (JSON.parse ETMEDEN önce), secret: whsec_…
export function verify(rawBody, header, secret, toleranceSec = 300) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const t = Number(parts.t);
  if (!t || Math.abs(Date.now() / 1000 - t) > toleranceSec) return false;
  const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1 ?? ""));
}

Python

import hmac, hashlib, time

def verify(raw_body: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    t = int(parts.get("t", 0))
    if abs(time.time() - t) > tolerance:
        return False
    expected = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts.get("v1", ""))

Delivery and retries

  • Your endpoint must return 2xx within 10 seconds; redirects are not followed.
  • Failed deliveries are retried after 1m, 5m, 30m, 2h, 6h and 12h. The same event may arrive more than once; deduplicate with X-Nlink-Delivery.
  • After 50 consecutive failures the webhook is disabled; you can re-enable it in the dashboard, where recent deliveries and errors are listed.
  • Event order is not guaranteed; use the created_at field.

Questions? [email protected]

Developers: Link Shortener API and Webhooks · nLink