आउटबाउंड वेबहुक: पेलोड और सिग्नेचर

आउटबाउंड वेबहुक AutoPSEO के अलर्ट, शेड्यूल की गई रिपोर्ट, टेस्ट मैसेज और रिपोर्ट सारांश आपके अपने एंडपॉइंट पर भेजता है। हर मैसेज एक JSON POST के रूप में जाता है, जिस पर HMAC-SHA256 से हस्ताक्षर होता है। इसका उपयोग 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 इस्तेमाल करने का सुझाव दिखता है।
• किसी टाइमर पर दोबारा प्रयास नहीं होता। विफल अलर्ट को भेजा हुआ चिह्नित नहीं किया जाता, इसलिए उसकी अगली जाँच में उसका फिर मूल्यांकन होता है और अगर वह अब भी ट्रिगर हो रहा हो तो पोस्ट किया जाता है: ज़्यादातर डिटेक्टर के लिए अगली सुबह, और index flip के लिए अगले घंटे। विफल शेड्यूल रिपोर्ट उसी अवधि में दोबारा नहीं भेजी जाती, इसलिए एंडपॉइंट ठीक करने के बाद Send now का उपयोग करें।
• id हर रिक्वेस्ट के लिए बनती है, इसलिए वह किसी इवेंट को नहीं बल्कि एक डिलीवरी को पहचानती है। अलर्ट की डुप्लिकेट पहचान के लिए event_type, site_url और occurred_at की तारीख को मिलाएँ: कोई नियम हर प्रॉपर्टी के लिए प्रति UTC दिन अधिकतम एक बार पोस्ट करता है, जब तक कोई Test rule न चलाए।

साइनिंग सीक्रेट

AutoPSEO signing secret को सिर्फ़ एक बार दिखाता है, जब आप वेबहुक सेव करते हैं, और सूची में वह दोबारा कभी नहीं दिखता। इसे तुरंत अपने रिसीवर के कॉन्फ़िगरेशन में, उस एंडपॉइंट के साथ ही सुरक्षित रख लें जिसकी यह रक्षा करता है।

URL खुद एन्क्रिप्टेड रूप में सहेजा जाता है, और सूची में केवल उसका होस्ट और आख़िरी कुछ अक्षर दिखते हैं। वेबहुक हटाने पर उस पर पोस्ट करने वाले सभी नियम भी हट जाते हैं। Teams चैनल में JSON की जगह पढ़ने योग्य कार्ड के लिए Microsoft Teams का उपयोग करें।