वेबहुक्स

वेबहुक दो सिस्टमों के बीच एक तंत्र, या एकीकरण है, जिसमें "उत्पादक" (FastComments) एक घटना उत्पन्न करता है जिसे "उपभोक्ता" (आप) एक API कॉल के माध्यम से उपभोग करता है।

FastComments केवल Comment रिसोर्स के लिए webhooks का समर्थन करता है।

हम कमेंट बनाने, हटाने और अपडेट होने पर webhooks का समर्थन करते हैं।

इनमें से प्रत्येक को हमारे सिस्टम में अलग-अलग इवेंट माना जाता है और इसलिए webhook इवेंट्स के लिए इनकी अलग-अलग semantics और संरचनाएँ होती हैं।

कोई भी संख्या में endpoints एक ही इवेंट की सदस्यता ले सकते हैं, चाहे dashboard से या API के माध्यम से (Managing Webhooks via the API देखें)। प्रत्येक webhook स्वतंत्र रूप से डिलीवर किया जाता है।

नए और एडिट वेबहुक पेजों में एक Send Test Payload बटन होता है जो फॉर्म में मौजूदा URL पर अनुरोध भेजता है, चाहे वह सेव किया गया हो या नहीं। Create और Update इवेंट्स एक डमी WebhookComment ऑब्जेक्ट भेजते हैं, जबकि Delete का परीक्षण करने पर केवल एक ID वाला डमी अनुरोध बॉडी भेजा जाता है।

पेलोड सत्यापित करना

अपने वेबहुक इंटीग्रेशन का परीक्षण करते समय, जांचें कि आने वाले अनुरोधों में निम्नलिखित हेडर शामिल हैं:

1. X-FastComments-Timestamp - Unix टाइमस्टैम्प (सेकंड)
2. X-FastComments-Signature - HMAC-SHA256 हस्ताक्षर

हस्ताक्षर योजना के लागू होने से पहले बनाए गए वेबहुक्स को आपके API Secret वाला एक token हेडर भी प्राप्त होता है। नए वेबहुक्स को नहीं।

पेलोड की प्रामाणिकता सुनिश्चित करने के लिए HMAC हस्ताक्षर सत्यापन का उपयोग करें।

परीक्षण उपकरण

विकास के दौरान आने वाले वेबहुक पेलोड की जांच के लिए आप webhook.site या ngrok जैसे उपकरणों का उपयोग कर सकते हैं।

इवेंट प्रकार

• Create Event: तब ट्रिगर होता है जब एक नई टिप्पणी बनाई जाती है।
• Update Event: तब ट्रिगर होता है जब कोई टिप्पणी संपादित की जाती है।
• Delete Event: तब ट्रिगर होता है जब कोई टिप्पणी हटाई जाती है।

प्रत्येक वेबहुक एक इवेंट और एक HTTP मेथड (POST, PUT या DELETE) से जुड़ा होता है। प्रत्येक इवेंट में अनुरोध बॉडी में पूरी टिप्पणी का डेटा शामिल होता है (पेलोड फॉर्मेट के लिए Data Structures देखें)।

वेबहुक के माध्यम से भेजी जाने वाली एकमात्र संरचना WebhookComment ऑब्जेक्ट है, जिसे नीचे TypeScript में दर्शाया गया है।

WebhookComment ऑब्जेक्ट की संरचना

"Create" इवेंट की संरचना

"create" इवेंट का रिक्वेस्ट बॉडी एक WebhookComment ऑब्जेक्ट होता है।

"Update" इवेंट की संरचना

"update" इवेंट का रिक्वेस्ट बॉडी एक WebhookComment ऑब्जेक्ट होता है।

"Delete" इवेंट की संरचना

"delete" इवेंट का रिक्वेस्ट बॉडी एक WebhookComment ऑब्जेक्ट होता है।

14 नवंबर 2023 का परिवर्तन
पहले "delete" इवेंट के रिक्वेस्ट बॉडी में केवल कमेंट की id होती थी। अब इसमें डिलीशन के समय का पूरा कमेंट होता है।

हर कुंजी (key) हमेशा बॉडी में मौजूद रहती है। जब किसी फ़ील्ड के लिए कमेंट में कोई मान नहीं होता, तो बॉडी में null होता है (बूलियन के लिए false और लिस्ट के लिए []), इसलिए डिलीवरी की संरचना एक कमेंट से दूसरे कमेंट में कभी नहीं बदलती।

WebhookComment ऑब्जेक्ट

Copy Run

1

2interface WebhookComment {

3 /** कमेंट की id। **/

4 id: string

5 /** कमेंट थ्रेड की पहचान करने वाली id या URL। सामान्यीकृत (Normalized)। **/

6 urlId: string

7 /** वह URL जो बताता है कि कमेंट कहाँ लिखा गया था। **/

8 url: string | null

9 /** कमेंट लिखने वाले यूज़र की id। SSO होने पर, tenant id के साथ प्रीफ़िक्स्ड। **/

10 userId: string | null

11 /** कमेंट लिखने वाले यूज़र का ईमेल। **/

12 commenterEmail: string | null

13 /** कमेंट विजेट में दिखने वाले यूज़र का नाम। SSO के साथ, यह displayName हो सकता है। **/

14 commenterName: string

15 /** रॉ (raw) कमेंट टेक्स्ट। **/

16 comment: string

17 /** पार्सिंग के बाद का कमेंट टेक्स्ट। **/

18 commentHTML: string

19 /** कमेंट की एक्सटर्नल id। **/

20 externalId: string | null

21 /** पैरेंट कमेंट की id। **/

22 parentId: string | null

23 /** वह UTC तारीख जब कमेंट लिखा गया था। **/

24 date: UTC_ISO_DateString

25 /** वोट्स का संयुक्त कर्मा (up - down)। **/

26 votes: number

27 votesUp: number

28 votesDown: number

29 /** True यदि कमेंट करते समय यूज़र लॉग इन था, या उसने कमेंट वेरिफ़ाई किया था, या कमेंट लिखते समय अपना सेशन वेरिफ़ाई किया था। **/

30 verified: boolean

31 /** वह UTC तारीख जब कमेंट वेरिफ़ाई किया गया था। **/

32 verifiedDate: UTC_ISO_DateString | null

33 /** यदि किसी मॉडरेटर ने कमेंट को रिव्यूड (reviewed) चिह्नित किया। **/

34 reviewed: boolean

35 /** अवतार (avatar) का लोकेशन, या base64 एनकोडिंग। केवल तब base64 होगा जब SSO के साथ यही मान भेजा गया हो। **/

36 avatarSrc: string | null

37 /** क्या कमेंट को मैन्युअली या स्वचालित रूप से स्पैम चिह्नित किया गया था? **/

38 isSpam: boolean

39 /** क्या कमेंट स्वचालित रूप से स्पैम चिह्नित किया गया था? **/

40 aiDeterminedSpam: boolean

41 /** क्या कमेंट में इमेज हैं? **/

42 hasImages: boolean

43 /** "Most Relevant" सॉर्ट दिशा के लिए कमेंट किस पेज नंबर पर है। **/

44 pageNumber: number | null

45 /** "Oldest First" सॉर्ट दिशा के लिए कमेंट किस पेज नंबर पर है। **/

46 pageNumberOF: number | null

47 /** "Newest First" सॉर्ट दिशा के लिए कमेंट किस पेज नंबर पर है। **/

48 pageNumberNF: number | null

49 /** क्या कमेंट स्वचालित रूप से या मैन्युअली अप्रूव किया गया था? **/

50 approved: boolean

51 /** कमेंट लिखते समय यूज़र का लोकेल कोड (फ़ॉर्मैट: en_us)। **/

52 locale: string | null

53 /** कमेंट में लिखे गए वे @mentions जो सफलतापूर्वक पार्स किए गए। कोई न होने पर खाली। **/

54 mentions: CommentUserMention[]

55 /** वह डोमेन जिससे कमेंट है। **/

56 domain: string | null

57 /** इस कमेंट से जुड़ी मॉडरेशन ग्रुप ids। कोई न होने पर खाली। **/

58 moderationGroupIds: string[]

59 /** इस कमेंट पर कमेंटर के नाम के आगे दिखाए गए बैज, इवेंट बनने के समय तक। कोई न होने पर खाली। **/

60 badges: CommentUserBadgeInfo[]

61}

62

जब किसी कमेंट में यूज़र्स को टैग किया जाता है, तो जानकारी mentions नामक लिस्ट में संग्रहीत होती है। उस लिस्ट के प्रत्येक ऑब्जेक्ट की निम्नलिखित संरचना होती है।

Webhook Mentions ऑब्जेक्ट

Copy Run

1

2interface CommentUserMention {

3 /** यूज़र की id। SSO यूज़र्स के लिए, इसमें आपकी tenant id प्रीफ़िक्स्ड होगी। **/

4 id: string

5 /** अंतिम @mention टैग टेक्स्ट, @ प्रतीक सहित। **/

6 tag: string

7 /** मूल @mention टैग टेक्स्ट, @ प्रतीक सहित। **/

8 rawTag: string

9 /** किस प्रकार के यूज़र को टैग किया गया। user = FastComments.com अकाउंट। sso = SSOUser। **/

10 type: 'user'|'sso'

11 /** यदि यूज़र नोटिफ़िकेशन से ऑप्ट आउट करता है, तो भी यह true पर सेट रहेगा। **/

12 sent: boolean

13}

14

badges लिस्ट की प्रत्येक एंट्री की निम्नलिखित संरचना होती है। बैज प्रकारों के लिए Badges गाइड देखें।

Webhook Badge ऑब्जेक्ट

Copy Run

1

2interface CommentUserBadgeInfo {

3 /** इस यूज़र को दिए गए बैज की id। **/

4 id: string

5 /** बैज का प्रकार। **/

6 type: number

7 /** बैज का विवरण, बैज पर होवर करने पर दिखता है। **/

8 description: string

9 /** बैज पर दिखाया गया टेक्स्ट। **/

10 displayLabel?: string | null

11 /** बैज के लिए दिखाई गई इमेज, यदि वह एक इमेज का उपयोग करता है। **/

12 displaySrc?: string | null

13 backgroundColor?: string | null

14 borderColor?: string | null

15 textColor?: string | null

16 /** बैज पर लागू एक अतिरिक्त CSS क्लास। **/

17 cssClass?: string | null

18}

19

HTTP मेथड्स

आप एडमिन पैनल में प्रत्येक वेबहुक इवेंट प्रकार के लिए HTTP मेथड कॉन्फ़िगर कर सकते हैं:

• Create इवेंट: POST या PUT (डिफ़ॉल्ट: PUT)
• Update इवेंट: POST या PUT (डिफ़ॉल्ट: PUT)
• Delete इवेंट: DELETE, POST, या PUT (डिफ़ॉल्ट: DELETE)

चूंकि सभी रिक्वेस्ट में एक ID होती है, Create और Update ऑपरेशन डिफ़ॉल्ट रूप से इडेम्पोटेंट (idempotent) होते हैं (PUT)। उसी Create या Update रिक्वेस्ट को दोहराने से आपकी तरफ़ डुप्लिकेट ऑब्जेक्ट नहीं बनने चाहिए।

रिक्वेस्ट हेडर्स

प्रत्येक वेबहुक रिक्वेस्ट में निम्नलिखित हेडर्स शामिल होते हैं:

HMAC सिग्नेचर सत्यापित करने की जानकारी के लिए Security & API Tokens देखें।

FastComments webhook अनुरोधों में सुरक्षा के लिए कई प्रमाणीकरण तंत्र शामिल हैं।

भेजे गए हेडर

HMAC हस्ताक्षर सत्यापन (अनुशंसित)

हम दृढ़ता से अनुशंसा करते हैं कि HMAC हस्ताक्षर को सत्यापित किया जाए ताकि यह सुनिश्चित हो सके कि webhook पेलोड प्रामाणिक हैं और उनमें छेड़छाड़ नहीं की गई है।

हस्ताक्षर प्रारूप: sha256=<hex-encoded-signature>

हस्ताक्षर की गणना कैसे होती है:

1. जोड़ें: timestamp + "." + JSON_payload_body
2. अपने API Secret को कुंजी के रूप में उपयोग करके HMAC-SHA256 गणना करें
3. परिणाम को हेक्स-एनकोड करें

सत्यापन उदाहरण (Node.js)

const crypto = require('crypto');

function verifyWebhookSignature(req, apiSecret) {
    const timestamp = req.headers['x-fastcomments-timestamp'];
    const signature = req.headers['x-fastcomments-signature'];

    if (!timestamp || !signature) {
        return false;
    }

    // सत्यापित करें कि टाइमस्टैम्प हाल का है (5 मिनट के भीतर)
    const now = Math.floor(Date.now() / 1000);
    if (Math.abs(now - parseInt(timestamp, 10)) > 300) {
        return false;  // रीप्ले अटैक की रोकथाम
    }

    // हस्ताक्षर सत्यापित करें
    const payload = JSON.stringify(req.body);
    const expectedSignature = crypto
        .createHmac('sha256', apiSecret)
        .update(`${timestamp}.${payload}`)
        .digest('hex');

    return signature === `sha256=${expectedSignature}`;
}

सत्यापन उदाहरण (Python)

import hmac
import hashlib
import time
import json

def verify_webhook_signature(headers, body, api_secret):
    timestamp = headers.get('X-FastComments-Timestamp')
    signature = headers.get('X-FastComments-Signature')

    if not timestamp or not signature:
        return False

    # सत्यापित करें कि टाइमस्टैम्प हाल का है
    now = int(time.time())
    if abs(now - int(timestamp)) > 300:
        return False

    # हस्ताक्षर सत्यापित करें
    payload = json.dumps(body, separators=(',', ':'))
    message = f"{timestamp}.{payload}"
    expected = hmac.new(
        api_secret.encode(),
        message.encode(),
        hashlib.sha256
    ).hexdigest()

    return signature == f"sha256={expected}"

सत्यापन उदाहरण (PHP)

function verifyWebhookSignature($headers, $body, $apiSecret) {
    $timestamp = $headers['X-FastComments-Timestamp'] ?? null;
    $signature = $headers['X-FastComments-Signature'] ?? null;

    if (!$timestamp || !$signature) {
        return false;
    }

    // सत्यापित करें कि टाइमस्टैम्प हाल का है (5 मिनट के भीतर)
    $now = time();
    if (abs($now - intval($timestamp)) > 300) {
        return false;
    }

    // हस्ताक्षर सत्यापित करें
    $payload = json_encode($body, JSON_UNESCAPED_SLASHES);
    $message = $timestamp . '.' . $payload;
    $expectedSignature = 'sha256=' . hash_hmac('sha256', $message, $apiSecret);

    return hash_equals($expectedSignature, $signature);
}

लेगेसी प्रमाणीकरण

आपके API Secret युक्त token हेडर पिछली संगतता के लिए अभी भी भेजा जाता है। हालाँकि, बेहतर सुरक्षा के लिए हम HMAC सत्यापन पर माइग्रेट करने की अनुशंसा करते हैं क्योंकि यह रीप्ले अटैक से सुरक्षा प्रदान करता है।

Webhooks को REST API के माध्यम से भी प्रबंधित किया जा सकता है। इसी तरह Zapier जैसी इंटीग्रेशन डैशबोर्ड को छुए बिना कमेंट इवेंट्स की सदस्यता लेती हैं, और यह REST Hooks पैटर्न का पालन करता है: सब्सक्राइब करें, इवेंट्स प्राप्त करें, अनसब्सक्राइब करें।

API सब्सक्रिप्शन डैशबोर्ड में कॉन्फ़िगर किए गए webhooks के साथ-साथ रहते हैं। एक कमेंट इवेंट हर उस webhook को डिलीवर किया जाता है जो उसके डोमेन से मेल खाता है, प्रत्येक अपनी अलग डिलीवरी के रूप में, चाहे webhook किसी भी तरह से बनाया गया हो।

प्रमाणीकरण

हर अनुरोध में x-api-key हेडर (या API_KEY क्वेरी पैरामीटर) में आपकी API Key और tenantId क्वेरी पैरामीटर में आपकी tenant ID चाहिए। दोनों डैशबोर्ड के API Secret पेज पर दिखाए जाते हैं।

सब्सक्राइब करें

POST https://fastcomments.com/api/v1/webhooks?tenantId=YOUR_TENANT_ID
x-api-key: YOUR_API_KEY
Content-Type: application/json

{
    "url": "https://hooks.zapier.com/hooks/catch/123/abc",
    "event": "comment-created"
}

प्रतिक्रिया में सब्सक्रिप्शन होता है:

{
    "status": "success",
    "webhook": {
        "id": "66f1c4c1e7a2b3d4f5a6b7c8",
        "url": "https://hooks.zapier.com/hooks/catch/123/abc",
        "event": "comment-created",
        "domain": "*",
        "method": "POST",
        "source": "api",
        "enabled": true,
        "createdAt": "2026-09-08T12:00:00.000Z"
    }
}

उसी URL को उसी इवेंट और डोमेन के लिए दोबारा सब्सक्राइब करने पर डुप्लिकेट बनाने के बजाय मौजूदा सब्सक्रिप्शन लौटाया जाता है, इसलिए क्लाइंट सुरक्षित रूप से रीट्राई कर सकता है। प्रत्येक tenant के पास अधिकतम 50 API सब्सक्रिप्शन हो सकते हैं।

सूची

GET https://fastcomments.com/api/v1/webhooks?tenantId=YOUR_TENANT_ID

Tenant के हर webhook को लौटाता है, जिनमें डैशबोर्ड में प्रबंधित वाले भी शामिल हैं ("source": "dashboard")। event, domain या source से फ़िल्टर करें।

अनसब्सक्राइब करें

DELETE https://fastcomments.com/api/v1/webhooks/SUBSCRIPTION_ID?tenantId=YOUR_TENANT_ID

किसी सब्सक्रिप्शन को डिलीट करने से उसके लिए कतार में मौजूद इवेंट्स भी हटा दिए जाते हैं। केवल API के माध्यम से बनाई गई सब्सक्रिप्शन ही इस तरह डिलीट की जा सकती हैं; डैशबोर्ड का webhook, या आपके खाते पर मौजूद न होने वाली कोई id, not-found कोड के साथ 404 लौटाता है। डैशबोर्ड webhooks को Webhooks पेज पर संपादित किया जाता है।

पेलोड और साइनिंग

डिलीवरी डैशबोर्ड webhooks के समान पेलोड का उपयोग करती हैं (Data Structures देखें) और उसी HMAC स्कीम से साइन की जाती हैं (Security & API Tokens देखें)। API सब्सक्रिप्शन को कभी भी लेगेसी token हेडर प्राप्त नहीं होता, इसलिए इसके बजाय X-FastComments-Signature हेडर सत्यापित करें।

नमूना पेलोड

GET https://fastcomments.com/api/v1/webhooks/sample-payloads?tenantId=YOUR_TENANT_ID&event=comment-created&limit=3

खाते की सबसे हाल की कमेंट्स को ठीक उसी आकार में लौटाता है जिस आकार में डिलीवरी होती है, ताकि कोई इंटीग्रेशन पहले इवेंट के आने से पहले वास्तविक नमूना डेटा दिखा सके। event वैकल्पिक है और केवल सत्यापित किया जाता है, क्योंकि हर इवेंट एक ही कमेंट ऑब्जेक्ट डिलीवर करता है। limit का डिफ़ॉल्ट 3 है और 1 से 10 स्वीकार करता है। 2 API क्रेडिट खर्च होते हैं।

{
    "status": "success",
    "payloads": [
        {
            "id": "66f1c4c1e7a2b3d4f5a6b7c8",
            "urlId": "https://example.com/blog/hello-world",
            "commenterName": "Jane Reader",
            "comment": "Great article!",
            "date": "2026-09-08T12:00:00.000Z",
            "approved": true
        }
    ]
}

410 Gone के साथ प्रतिक्रिया देना

यदि किसी API सब्सक्रिप्शन का एंडपॉइंट HTTP 410 Gone के साथ प्रतिक्रिया देता है, तो FastComments इसे अनसब्सक्राइब के रूप में मानता है: सब्सक्रिप्शन उसके कतार में मौजूद इवेंट्स के साथ डिलीट कर दिया जाता है, और आगे कोई डिलीवरी का प्रयास नहीं किया जाता। डैशबोर्ड में कॉन्फ़िगर किए गए webhooks कभी भी स्वचालित रूप से डिलीट नहीं किए जाते; उनके लिए 410 एक सामान्य विफलता है। कोई अन्य विफलता स्थिति रीट्राई की जाती है और अंततः webhook अक्षम कर दिया जाता है, जैसा कि How it Works & Handling Retries में वर्णित है।

डैशबोर्ड

API सब्सक्रिप्शन Webhooks सूची में स्रोत API के साथ दिखाई देते हैं, जहाँ एक व्यवस्थापक उन्हें संपादित, अक्षम, पुनः सक्षम या डिलीट कर सकता है।