ویب ہُکس: ایونٹس، پے لوڈ اور دستخط

ویب ہُک آپ کے سرور کو ایک HTTP ریکویسٹ بھیجتا ہے جیسے ہی آپ کی ورک اسپیس میں کچھ ہوتا ہے – مثلاً جب کوئی صفحہ شائع ہو۔ اس طرح آپ کو بار بار پوچھنا نہیں پڑتا کہ کچھ بدلا ہے یا نہیں۔ ہر ڈیلیوری پر دستخط ہوتے ہیں تاکہ آپ کا سرور اصلی پیغامات کو جعلی پیغامات سے الگ پہچان سکے۔

#ضروریات

• ورک اسپیس میں مالک یا ایڈمن – “ویب ہُکس” مینو آئٹم صرف انہی رولز کے لیے نظر آتا ہے
• Creator Pro سے؛ Creator Free میں لکھا ہوتا ہے “ویب ہُکس Creator Pro سے دستیاب ہیں۔”
• Creator Pro میں 5 تک ویب ہُکس، Creator Agency میں 25، Enterprise میں 100 (قابل تبدیل)
• ایک سرور جس تک عوامی https پتے پر پہنچا جا سکے

ویب ہُکس آپ صرف ڈیش بورڈ میں سنبھالتے ہیں۔ انہیں API کلیدوں سے بنایا یا تبدیل نہیں کیا جا سکتا۔

#ویب ہُک بنائیں

1. نیویگیشن میں “ویب ہُکس” کھولیں
2. “+ نیا ویب ہُک” پر کلک کریں
3. ہدف URL درج کریں اور ایونٹس چنیں
4. اختیاری: تفصیل درج کریں اور اسٹیٹس چنیں
5. “ویب ہُک بنائیں” پر کلک کریں
6. “مکمل” مرحلے میں سائننگ سیکرٹ (“سائننگ سیکرٹ – صرف ابھی نظر آ رہا ہے”) کاپی کر کے اپنے سرور پر محفوظ کریں – یہ صرف ابھی دکھایا جاتا ہے
7. “ٹیسٹ” سے ویب ہُک آزمائیں؛ نتیجہ اگلے ٹیسٹ تک کارڈ پر رہتا ہے: “کامیابی سے پہنچ گیا” یا “نہیں پہنچا”، HTTP کوڈ (یا “کوئی جواب نہیں”)، دورانیہ اور جواب کے آغاز کے ساتھ

“ہدف URL (https://…)”

2048 حروف تک۔ صرف https، URL میں لاگ اِن کی معلومات نہیں، localhost پتے نہیں اور .local، .internal یا .lan جیسے اندرونی نام نہیں۔ نام کو عوامی IP پتوں کی طرف اشارہ کرنا چاہیے؛ LinkHarbor ہر ڈیلیوری سے پہلے یہ دوبارہ چیک کرتا ہے۔

“ایونٹس”

کم از کم ایک ایونٹ۔ ہر گروپ میں “سب منتخب کریں” اور “سب کا انتخاب ختم کریں” ہوتے ہیں۔

“تفصیل”

اختیاری، 255 حروف تک – مثلاً یہ کہ ویب ہُک کس لیے ہے۔

“اسٹیٹس”

“فعال” یا “بند”۔ بند ویب ہُکس کو کوئی ڈیلیوری نہیں ملتی۔

#ایونٹس

form.submitted میں قدریں بالکل ویسی ہوتی ہیں جیسی وزیٹر نے جمع کرائیں، لیکن اس کا IP پتہ یا براؤزر کبھی نہیں۔ ڈیلیوری پس منظر میں چلتی ہے: وزیٹر اس کا انتظار نہیں کرتا، اور ناکام ڈیلیوری جمع کرانے کو نہیں روکتی۔

#ڈیلیوری کی ساخت

LinkHarbor ہر ڈیلیوری JSON باڈی اور ان ہیڈرز کے ساتھ POST کے طور پر بھیجتا ہے:

{
  "id": "3f1c2a9e-8d4b-4a51-9f0e-6b7c1d2e3f40",
  "event": "page.published",
  "created_at": "2026-11-01T09:30:12+00:00",
  "data": {
    "page_id": 42,
    "version": 8,
    "checksum": "9b1e5c…",
    "published_by_user_id": 7
  }
}

دوبارہ ڈیلیوریز کو نئی id کے ساتھ redelivery_of (دہرائی جانے والی ڈیلیوری کی ID) اور delivery_root (اس سلسلے کی پہلی ڈیلیوری کی ID) فیلڈز بھی ملتی ہیں۔

#دستخط کی تصدیق کریں

ہر ویب ہُک کا اپنا سائننگ سیکرٹ ہوتا ہے (32 hex حروف)۔ آپ اسے صرف ایک بار دیکھتے ہیں: ویب ہُک بناتے وقت آخری مرحلے میں اور “سیکرٹ ↺” کے فوراً بعد۔ اسے فوراً اپنے سرور پر کاپی کریں – LinkHarbor اسے بعد میں دوبارہ نہیں دکھاتا۔ LinkHarbor اس سے دستخط یوں بناتا ہے:

1. پیغام بنائیں: ٹائم اسٹیمپ، نقطہ، ڈیلیوری ID، نقطہ، خام باڈی – یعنی timestamp.delivery_id.body
2. اس پیغام پر سائننگ سیکرٹ کو کلید بنا کر HMAC-SHA256 کا حساب لگائیں
3. نتیجہ sha256= کے سابقے کے ساتھ hex اسٹرنگ کے طور پر بھیجیں

آپ کے سرور کو دستخط کو constant-time موازنے سے چیک کرنا چاہیے، 300 سیکنڈ سے پرانے ٹائم اسٹیمپ والی ڈیلیوریز مسترد کرنی چاہییں اور دہرائی گئی ڈیلیوریز پہچاننے کے لیے ڈیلیوری IDs کم از کم اتنی دیر محفوظ رکھنی چاہییں۔ اہم: خام باڈی پر دستخط ہوتے ہیں، بالکل ویسی جیسی پہنچتی ہے – نہ کہ وہ JSON جسے آپ نے دوبارہ انکوڈ کیا ہو۔

import crypto from 'node:crypto';
import express from 'express';

const app = express();
const SECRET = process.env.LH_WEBHOOK_SECRET;
const seen = new Set(); // in production: a database or Redis with expiry

app.post('/webhooks/linkharbor', express.raw({ type: 'application/json' }), (req, res) => {
  const ts = req.get('X-LinkHarbor-Timestamp') || '';
  const id = req.get('X-LinkHarbor-Delivery-Id') || '';
  const sig = req.get('X-LinkHarbor-Signature') || '';

  if (!/^\d+$/.test(ts) || Math.abs(Date.now() / 1000 - Number(ts)) > 300) {
    return res.status(400).send('timestamp');
  }

  const expected = 'sha256=' + crypto
    .createHmac('sha256', SECRET)
    .update(ts + '.' + id + '.')
    .update(req.body) // raw body as a Buffer
    .digest('hex');

  const a = Buffer.from(expected);
  const b = Buffer.from(sig);
  if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
    return res.status(401).send('signature');
  }

  const event = JSON.parse(req.body.toString('utf8'));
  const key = event.delivery_root || event.id; // recognise redeliveries of the same chain
  if (!seen.has(key)) {
    seen.add(key);
    // process here, ideally asynchronously in a queue
  }
  res.sendStatus(200);
});

app.listen(3000);

<?php
$secret = getenv('LH_WEBHOOK_SECRET');
$body   = file_get_contents('php://input');
$ts     = $_SERVER['HTTP_X_LINKHARBOR_TIMESTAMP'] ?? '';
$id     = $_SERVER['HTTP_X_LINKHARBOR_DELIVERY_ID'] ?? '';
$sig    = $_SERVER['HTTP_X_LINKHARBOR_SIGNATURE'] ?? '';

if (!ctype_digit($ts) || abs(time() - (int)$ts) > 300) {
    http_response_code(400);
    exit('timestamp');
}

$expected = 'sha256=' . hash_hmac('sha256', $ts . '.' . $id . '.' . $body, $secret);
if (!hash_equals($expected, $sig)) {
    http_response_code(401);
    exit('signature');
}

$event = json_decode($body, true);
// Recognise duplicate deliveries by $event['delivery_root'] ?? $event['id'],
// then process.
http_response_code(200);

curl سے اپنا اینڈپوائنٹ آزمائیں

یہ اسکرپٹ آپ کے اپنے سرور کو درست دستخط والی ٹیسٹ ڈیلیوری بھیجتا ہے – LinkHarbor میں ویب ہُک بنانے سے پہلے کارآمد:

SECRET="your-signing-secret"
URL="https://example.com/webhooks/linkharbor"
TS=$(date +%s)
ID=$(uuidgen | tr 'A-Z' 'a-z')
BODY='{"id":"'"$ID"'","event":"webhook.test","created_at":"2026-11-01T09:30:12+00:00","data":{"message":"یہ اس ویب ہُک کے لیے ایک ٹیسٹ ایونٹ ہے۔"}}'
SIG="sha256=$(printf '%s' "$TS.$ID.$BODY" | openssl dgst -sha256 -hmac "$SECRET" -hex | sed 's/^.* //')"

curl -X POST "$URL" \
  -H "Content-Type: application/json" \
  -H "X-LinkHarbor-Event: webhook.test" \
  -H "X-LinkHarbor-Delivery-Id: $ID" \
  -H "X-LinkHarbor-Timestamp: $TS" \
  -H "X-LinkHarbor-Signature: $SIG" \
  -H "X-LinkHarbor-Signature-Version: v1" \
  -d "$BODY"

#جواب، ٹائم آؤٹ اور دوبارہ ڈیلیوری

• 2xx اسٹیٹس والا کوئی بھی جواب کامیابی شمار ہوتا ہے؛ ری ڈائریکٹس (3xx) کی پیروی نہیں کی جاتی
• آپ کے سرور کے پاس جواب دینے کے لیے 10 سیکنڈ ہیں، اور کنکشن قائم کرنے کے لیے زیادہ سے زیادہ 5 سیکنڈ
• ایک ایونٹ کے تمام ویب ہُکس کے پاس مل کر کل 25 سیکنڈ ہوتے ہیں؛ جن کی باری تب تک نہ آئے وہ ناکام شمار ہوتے ہیں اور دوبارہ بھیجے جا سکتے ہیں
• LinkHarbor ناکام ڈیلیوریز کو خود بخود دوبارہ نہیں آزماتا
• ناکام ڈیلیوریز آپ ہاتھ سے دوبارہ بھیج سکتے ہیں، لیکن وہ نہیں جو اس دوران کامیاب ہو چکی ہو؛ دوبارہ ڈیلیوری کی نئی id اور نیا created_at ہوتا ہے
• ہر ایونٹ کے لیے پہلی ڈیلیوری سمیت زیادہ سے زیادہ 3 کوششوں کی اجازت ہے؛ اس کے بعد وہ “ڈیڈ لیٹرز” میں چلا جاتا ہے اور دوبارہ نہیں بھیجا جا سکتا

#ڈیش بورڈ میں ڈیلیوریز

“ڈیلیوریز” کسی ویب ہُک کا لاگ کھولتا ہے۔ اس میں تین ٹیبز ہیں:

“تمام ڈیلیوریز”

تمام ڈیلیوریز، ایونٹ، اسٹیٹس (“کامیاب (2xx)”، “کلائنٹ کی خرابی (4xx)”، “سرور کی خرابی (5xx)”، “ناکام”) اور “حد” کے فلٹرز کے ساتھ۔ “↺ دوبارہ کوشش” ناکام ڈیلیوری کو دوبارہ بھیجتا ہے، جب تک کہ بعد کی کوئی کامیاب ڈیلیوری نہ ہو۔ کسی قطار پر کلک کرنے سے ریکویسٹ، جواب، باڈی اور خام JSON نظر آتے ہیں۔

“ری پلیز”

دوبارہ ڈیلیوریز کے سلسلے، “بحال ہو گیا” یا “اب بھی ناکام” نتیجے اور کوششوں کی تعداد کے ساتھ۔

“ڈیڈ لیٹرز”

وہ ڈیلیوریز جن میں تمام اجازت شدہ کوششیں ناکام رہیں – پہلی ڈیلیوری اور دوبارہ ڈیلیوریز ملا کر۔ یہ ٹیب صرف دیکھنے کے لیے ہے: انہیں اب دوبارہ نہیں بھیجا جا سکتا۔ اپنا اینڈپوائنٹ چیک کریں؛ اس کے بعد نئے ایونٹس معمول کے مطابق پہنچیں گے۔ اگر آپ کو ڈیٹا چاہیے تو اسے API کے ذریعے حاصل کریں۔

اگر دوبارہ ڈیلیوری نہ ہو سکے تو ڈیش بورڈ وجہ بتاتا ہے:

“دوبارہ نہیں بھیجا گیا: یہ ایونٹ پہلے ہی … بار ناکام ہو چکا ہے، مزید کوشش ممکن نہیں۔ یہ آپ کو ‘ڈیڈ لیٹرز’ میں ملے گا۔”

تمام 3 کوششیں استعمال ہو چکی ہیں۔

“دوبارہ نہیں بھیجا گیا: یہ ایونٹ اس دوران کامیابی سے پہنچ چکا ہے۔”

اسی سلسلے کی بعد کی ایک ڈیلیوری پہلے ہی کامیاب ہو چکی ہے۔

#ڈیش بورڈ میں تصدیق

“تصدیق” کے تحت آپ کو دو مددگار چیزیں ملیں گی:

“تصدیقی کٹ”

“کٹ لوڈ کریں” الگورتھم، ہیڈرز کے نام، دستخط شدہ پیغام کا فارمیٹ اور 300 سیکنڈ کی تجویز کردہ گنجائش دکھاتا ہے۔ خود سیکرٹ اس میں شامل نہیں۔

“دستخط کی تصدیق کریں”

موصول شدہ ڈیلیوری کی ڈیلیوری ID، ٹائم اسٹیمپ، دستخط اور خام ریکویسٹ باڈی درج کریں۔ پھر LinkHarbor آپ کو بتاتا ہے “دستخط درست ہے” یا “دستخط درست نہیں”۔ ٹائم اسٹیمپ اور دستخط X-LinkHarbor-Timestamp اور X-LinkHarbor-Signature ہیڈرز سے کاپی کریں۔ یہ جانچ صرف پچھلے 5 منٹ کی ڈیلیوریز کے لیے کام کرتی ہے؛ پرانی ڈیلیوریز کے لیے یہ “دستخط درست نہیں” بتاتی ہے، چاہے دستخط درست ہوں۔

#سیکرٹ تبدیل کریں، بند کریں، حذف کریں

• “سیکرٹ ↺” نیا سائننگ سیکرٹ بناتا ہے اور اسے ایک بار دکھاتا ہے؛ پرانا فوراً کام کرنا بند کر دیتا ہے، اور آپ کے سرور کو نیا استعمال کرنا ہوگا
• ڈیلیوریز روکنے کے لیے “ترمیم کریں” میں اسٹیٹس کو “بند” پر سیٹ کریں
• کوڑے دان کا آئیکن ویب ہُک حذف کرتا ہے؛ پیغام بند کرنے تک آپ “واپس کریں” سے منسوخ کر سکتے ہیں

جب آپ چھوٹے پلان پر جاتے ہیں تو نئی حد سے زیادہ ویب ہُکس بند ہو جاتے ہیں، اور Creator Free میں سب۔ وہ محفوظ رہتے ہیں؛ اپ گریڈ کے بعد LinkHarbor بند ویب ہُکس کو نئے پلان کی حد تک خود بخود دوبارہ فعال کر دیتا ہے – ان سمیت جو آپ نے خود بند کیے تھے۔