Webhooks

Configure delivery

Set a webhook URL in Domain Settings → Tracking. ShortFreeURL sends JSON with an X-ShortFreeURL-Signature header and records the outcome in the delivery log.

{
  "event": "click.created",
  "shortURL": "https://go.example.com/summer",
  "path": "summer",
  "country": "IN",
  "city": "Mumbai",
  "browser": "Chrome",
  "human": true,
  "timestamp": "2026-09-10T10:00:00.000Z"
}

Verify the signature

The X-ShortFreeURL-Signature header value is sha256=<hex>. Strip the prefix before comparing, or compare against a value that includes it.

import crypto from 'node:crypto';

const expected = 'sha256=' + crypto.createHmac('sha256', process.env.WEBHOOK_SECRET)
  .update(rawBody).digest('hex');
const header = String(signature || '');
const valid = header.length === expected.length && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(header));

import hashlib, hmac, os
expected = "sha256=" + hmac.new(os.environ["WEBHOOK_SECRET"].encode(), raw_body, hashlib.sha256).hexdigest()
valid = hmac.compare_digest(expected, signature or "")

$expected = 'sha256=' . hash_hmac('sha256', $rawBody, getenv('WEBHOOK_SECRET'));
$valid = hash_equals($expected, (string)$signature);

Delivery rules

• Answer with any 2xx status only after the event is durably accepted.
• Deduplicate with the click or conversion id.
• Process asynchronously so your endpoint answers quickly.
• Use the dashboard test event before enabling production traffic.