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

آؤٹ باؤنڈ ویب ہُک AutoPSEO کے الرٹس، شیڈول شدہ رپورٹس، ٹیسٹ پیغامات اور رپورٹ کے خلاصے آپ کے اپنے اینڈ پوائنٹ پر بھیجتا ہے۔ ہر پیغام HMAC-SHA256 سے دستخط شدہ ایک JSON POST ہوتا ہے۔ اسے Zapier، Make، n8n، انسیڈنٹ ٹول یا اپنے کوڈ میں ڈیٹا پہنچانے کے لیے استعمال کریں؛ اس کے لیے Slack یا Teams اکاؤنٹ کی ضرورت نہیں۔ کیا آپ وہ ویب ہُک ڈھونڈ رہے ہیں جو آرٹیکلز آپ کی سائٹ تک پہنچاتا ہے؟ وہ کنٹینٹ انجن کا حصہ ہے: کنٹینٹ ڈیلیوری دیکھیں۔

ویب ہُک شامل کریں

1. Outbound webhooks سیکشن میں New webhook پر کلک کریں۔
2. اسے ایک Name دیں اور اینڈ پوائنٹ کا URL پیسٹ کریں۔ یہ عوامی HTTPS ہونا چاہیے: سادہ http، localhost، .local یا .internal پر ختم ہونے والے نام، بغیر ڈاٹ والے ہوسٹ، اور نجی یا لنک لوکل IP ایڈریس قبول نہیں کیے جاتے۔
3. محفوظ کرنے کے بعد دکھایا جانے والا signing secret کاپی کر لیں۔ یہ صرف ایک بار دکھایا جاتا ہے۔
4. test ایونٹ بھیجنے کے لیے Send test پر کلک کریں، پھر ویب ہُک کے ساتھ شیڈول شدہ رپورٹس یا الرٹس منسلک کریں۔

ویب ہُک ریکویسٹ کیسی نظر آتی ہے

ہر پیغام ان ہیڈرز کے ساتھ ایک POST ہوتا ہے:

یہ 12 اکتوبر 2026 کو 06:00 UTC کی رن سے ایک ڈومین پراپرٹی کا ٹریفک ڈراپ الرٹ ہے، جسے پڑھنے کی سہولت کے لیے فارمیٹ کیا گیا ہے (اصل ترسیل میں یہ کمپیکٹ JSON ہوتا ہے، اور id اور site_id کی قدریں فرضی ہیں):

{
  "id": "9b2e61f04c3a4d7e8f15a0b6c2d39e47",
  "event_type": "traffic_drop",
  "severity": "high",
  "site_id": "4f0c1e9a2b7d4c58",
  "site_url": "sc-domain:example.com",
  "occurred_at": "2026-10-12T06:00:04.183Z",
  "title": "Traffic drop: example.com",
  "text": "Clicks 1,500 vs 2,000 in the previous window (-25.0%).",
  "url": "https://app.autopseo.com/property/sc-domain%3Aexample.com",
  "payload": {
    "fields": [
      { "label": "Metric", "value": "clicks" },
      { "label": "Current", "value": "1,500" },
      { "label": "Baseline", "value": "2,000" },
      { "label": "Window", "value": "7 days (2026-10-05 → 2026-10-11 vs 2026-09-28 → 2026-10-04)" },
      { "label": "Change", "value": "-25.0%" }
    ],
    "table": null,
    "detector": "traffic_drop",
    "window": 7,
    "range": { "start": "2026-10-05", "end": "2026-10-11", "compStart": "2026-09-28", "compEnd": "2026-10-04" },
    "result": {
      "fired": true,
      "metric": "clicks",
      "value": 1500,
      "baseline": 2000,
      "change": -0.25,
      "severity": "high",
      "summary": "Clicks 1,500 vs 2,000 in the previous window (-25.0%)."
    }
  },
  "source": "autopseo"
}

اوپری سطح کے فیلڈز ہر ایونٹ میں یکساں ہوتے ہیں:

تناسب اعشاریہ کسر کی صورت میں ہوتے ہیں: -0.25 کی change کا مطلب 25% کی کمی ہے، اور 0.034 کے ctr کا مطلب 3.4% ہے۔

ایونٹ کی اقسام

result وہی دہراتا ہے جو ڈیٹیکٹر نے ناپا: fired، metric، value، baseline، change (جب موازنے کے لیے کچھ نہ ہو تو null)، severity اور summary، اور anomaly کے لیے اس کے علاوہ z، یعنی ماڈیفائیڈ z-اسکور۔ totals اور previous میں رپورٹ کی دونوں مدتوں کے لیے clicks، impressions، ctr اور position ہوتے ہیں۔ ہر ڈیٹیکٹر کیا ناپتا ہے، اس کی تفصیل الرٹس میں ہے۔

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

دستخط اُن عین بائٹس کا HMAC-SHA256 ہوتا ہے جو AutoPSEO نے بھیجے، جس کی کلید ویب ہُک کا signing secret ہے، اور جسے sha256= اور چھوٹے ہیکس حروف کی شکل میں لکھا جاتا ہے۔ تصدیق کے لیے:

1. JSON پارس کرنے سے پہلے خام ریکویسٹ باڈی پڑھیں۔ پارس کر کے دوبارہ سیریلائز کرنے سے بائٹس بدل سکتے ہیں۔
2. انہی بائٹس پر HMAC-SHA256 نکالیں، اور secret کو متن کے طور پر استعمال کریں: یعنی 64 حروف کی وہی اسٹرنگ جیسی دکھائی گئی تھی، ہیکس سے ڈی کوڈ کیے بغیر۔
3. نتیجے کے شروع میں sha256= لگائیں اور اسے X-AutoPSEO-Signature ہیڈر سے کانسٹنٹ ٹائم میں موازنہ کریں۔
4. اگر دونوں مختلف ہوں تو ریکویسٹ مسترد کر دیں۔ ورنہ فوراً 2xx اسٹیٹس کے ساتھ جواب دیں اور وقت لینے والا کام بعد میں کریں۔

Node.js کے لیے بغیر کسی ڈیپنڈنسی کے ایک ریسیور:

import { createServer } from 'node:http';
import { createHmac, timingSafeEqual } from 'node:crypto';

const secret = process.env.AUTOPSEO_WEBHOOK_SECRET;

createServer((req, res) => {
  const chunks = [];
  req.on('data', (chunk) => chunks.push(chunk));
  req.on('end', () => {
    const raw = Buffer.concat(chunks);
    const expected = Buffer.from('sha256=' + createHmac('sha256', secret).update(raw).digest('hex'));
    const received = Buffer.from(String(req.headers['x-autopseo-signature'] || ''));
    if (received.length !== expected.length || !timingSafeEqual(received, expected)) {
      res.writeHead(401).end();
      return;
    }
    res.writeHead(204).end();
    const event = JSON.parse(raw.toString('utf8'));
    console.log(event.event_type, event.severity, event.site_url);
  });
}).listen(8080);

لمبائی کی جانچ پہلے اس لیے کی جاتی ہے کہ Node کا timingSafeEqual دونوں بفرز کی لمبائی مختلف ہونے پر ایرر دیتا ہے۔

ڈیلیوری کے اصول

• ہر پیغام کی ایک کوشش ہوتی ہے جس کا ٹائم آؤٹ 10 سیکنڈ ہے۔ 2xx کے علاوہ کوئی بھی جواب ناکامی شمار ہوتا ہے اور اسٹیٹس کوڈ اور آپ کی رسپانس باڈی کے ابتدائی حصے کے ساتھ Delivery history میں محفوظ رہتا ہے۔
• ری ڈائریکٹس فالو نہیں کیے جاتے۔ 3xx جواب ناکام ہو جاتا ہے اور ساتھ نوٹ آتا ہے کہ حتمی URL استعمال کریں۔
• کسی ٹائمر پر کچھ دوبارہ نہیں بھیجا جاتا۔ ناکام الرٹ کو "بھیجا گیا" کے طور پر نشان زد نہیں کیا جاتا، اس لیے اگلی جانچ میں اسے دوبارہ پرکھا جاتا ہے اور اگر وہ اب بھی فائر ہو رہا ہو تو پوسٹ ہو جاتا ہے: زیادہ تر ڈیٹیکٹرز کے لیے اگلی صبح، اور انڈیکس فلپس کے لیے اگلے گھنٹے میں۔ ناکام شیڈول شدہ رپورٹ اسی مدت میں دوبارہ نہیں بھیجی جاتی، اس لیے اینڈ پوائنٹ ٹھیک کرنے کے بعد Send now استعمال کریں۔
• id ہر ریکویسٹ کے لیے الگ بنتی ہے، اس لیے یہ کسی ایونٹ کی نہیں بلکہ ایک ڈیلیوری کی شناخت کرتی ہے۔ الرٹس کی تکرار ہٹانے کے لیے event_type، site_url اور occurred_at کی تاریخ کو ملا کر استعمال کریں: ایک رول ہر پراپرٹی کے لیے ہر UTC دن میں زیادہ سے زیادہ ایک بار پوسٹ کرتا ہے، سوائے اس کے کہ کوئی Test rule چلائے۔

Signing secret

AutoPSEO signing secret صرف ایک بار دکھاتا ہے، یعنی ویب ہُک محفوظ کرتے وقت، اور فہرست اسے دوبارہ کبھی نہیں دکھاتی۔ اسے فوراً اپنے ریسیور کی کنفیگریشن کے ساتھ، اسی اینڈ پوائنٹ کے ساتھ محفوظ کر لیں جس کی یہ حفاظت کرتا ہے۔

URL خود انکرپٹڈ صورت میں محفوظ ہوتا ہے، اور فہرست میں صرف اس کا ہوسٹ اور آخری چند حروف دکھائے جاتے ہیں۔ ویب ہُک حذف کرنے سے وہ تمام رولز بھی حذف ہو جاتے ہیں جو اس پر پوسٹ کرتے ہیں۔ اگر آپ Teams چینل میں JSON کے بجائے پڑھنے کے قابل کارڈ چاہتے ہیں تو Microsoft Teams استعمال کریں۔