Webhooks: इवेंट, पेलोड और सिग्नेचर

Webhook आपके वर्कस्पेस में कुछ होते ही आपके सर्वर को एक HTTP अनुरोध भेजता है – जैसे जब कोई पेज पब्लिश होता है। इससे आपको बार-बार पूछना नहीं पड़ता कि कुछ बदला है या नहीं। हर डिलीवरी साइन की जाती है, ताकि आपका सर्वर असली संदेशों को नक़ली से अलग पहचान सके।

#ज़रूरी बातें

• वर्कस्पेस में मालिक या एडमिन – “Webhooks” मेन्यू आइटम सिर्फ़ इन भूमिकाओं को दिखता है
• Creator Pro से; Creator Free में लिखा होता है “Webhooks Creator Pro से उपलब्ध हैं।”
• Creator Pro में 5 तक, Creator Agency में 25 तक, Enterprise में 100 तक webhooks (बदला जा सकता है)
• एक सर्वर जो किसी सार्वजनिक https पते पर पहुँचा जा सके

Webhooks आप सिर्फ़ डैशबोर्ड में मैनेज करते हैं। इन्हें API keys से बनाया या बदला नहीं जा सकता।

#Webhook बनाएँ

1. नेविगेशन में “Webhooks” खोलें
2. “+ नया Webhook” पर क्लिक करें
3. लक्ष्य URL डालें और इवेंट चुनें
4. वैकल्पिक: एक विवरण डालें और स्थिति चुनें
5. “Webhook बनाएँ” पर क्लिक करें
6. “हो गया” चरण में साइनिंग secret (“साइनिंग Secret — सिर्फ़ अभी दिख रहा है”) कॉपी करें और अपने सर्वर पर रखें – यह सिर्फ़ अभी दिखता है
7. “टेस्ट” से webhook जाँचें। नतीजा अगले टेस्ट तक कार्ड पर रहता है: “सफलतापूर्वक डिलीवर हुआ” या “डिलीवर नहीं हुआ”, HTTP कोड (या “कोई जवाब नहीं”), अवधि और जवाब की शुरुआत के साथ

“लक्ष्य URL (https://…)”

ज़्यादा से ज़्यादा 2048 अक्षर। सिर्फ़ https, URL में कोई लॉगिन जानकारी नहीं, कोई localhost पता नहीं और .local, .internal या .lan जैसे कोई आंतरिक नाम नहीं। नाम को सार्वजनिक IP पतों की ओर इशारा करना चाहिए; LinkHarbor हर डिलीवरी से पहले इसे फिर जाँचता है।

“इवेंट”

कम से कम एक इवेंट। हर समूह में “सभी चुनें” और “सभी का चयन हटाएँ” होते हैं।

“विवरण”

वैकल्पिक, ज़्यादा से ज़्यादा 255 अक्षर – जैसे webhook किस लिए है।

“स्थिति”

“सक्रिय” या “बंद”। बंद webhooks को कोई डिलीवरी नहीं मिलती।

#इवेंट

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) फ़ील्ड।

#सिग्नेचर सत्यापित करें

हर webhook का अपना साइनिंग secret होता है (32 hex अक्षर)। आप इसे ठीक एक बार देखते हैं: webhook बनाते समय आख़िरी चरण में और “Secret ↺” के ठीक बाद। इसे तुरंत अपने सर्वर पर कॉपी करें – LinkHarbor इसे बाद में फिर नहीं दिखाता। LinkHarbor इससे सिग्नेचर इस तरह गिनता है:

1. संदेश बनाएँ: timestamp, डॉट, delivery ID, डॉट, raw बॉडी – यानी timestamp.delivery_id.body
2. साइनिंग secret को key बनाकर इस संदेश पर HMAC-SHA256 गिनें
3. नतीजे को sha256= प्रीफ़िक्स के साथ hex स्ट्रिंग के रूप में भेजें

आपके सर्वर को सिग्नेचर constant-time तुलना से जाँचना चाहिए, 300 सेकंड से पुराने timestamp वाली डिलीवरी अस्वीकार करनी चाहिए और दोहराव पहचानने के लिए delivery IDs कम से कम उतने समय तक सहेजनी चाहिए। ज़रूरी: raw बॉडी साइन होती है, ठीक वैसी जैसी पहुँचती है – आपका दोबारा एन्कोड किया JSON नहीं।

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

const app = express();
const SECRET = process.env.LH_WEBHOOK_SECRET;
const seen = new Set(); // प्रोडक्शन में: expiry वाला डेटाबेस या Redis

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) // Buffer के रूप में raw बॉडी
    .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; // उसी शृंखला की दोबारा डिलीवरी पहचानें
  if (!seen.has(key)) {
    seen.add(key);
    // यहाँ प्रोसेस करें, अच्छा हो कि किसी queue में asynchronously
  }
  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);
// दोहराई गई डिलीवरी $event['delivery_root'] ?? $event['id'] से पहचानें,
// फिर प्रोसेस करें।
http_response_code(200);

curl से अपना एंडपॉइंट जाँचें

यह स्क्रिप्ट आपके अपने सर्वर पर सही तरह साइन की गई एक टेस्ट डिलीवरी भेजती है – LinkHarbor में webhook बनाने से पहले काम की। असली टेस्ट में data.message आपकी भाषा में होता है, इसलिए इस पर मिलान न करें:

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":"यह इस webhook के लिए एक टेस्ट इवेंट है।"}}'
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 सेकंड
• एक इवेंट के सभी webhooks कुल 25 सेकंड साझा करते हैं; जिनकी बारी तब तक नहीं आती, वे विफल चिह्नित होते हैं और दोबारा भेजे जा सकते हैं
• LinkHarbor विफल डिलीवरी अपने आप दोबारा नहीं भेजता
• विफल डिलीवरी आप हाथ से दोबारा भेज सकते हैं, लेकिन वह नहीं जो इस बीच सफल हो चुकी है। दोबारा भेजी गई डिलीवरी की नई id और नया created_at होता है
• हर इवेंट पर पहली डिलीवरी समेत ज़्यादा से ज़्यादा 3 कोशिशों की अनुमति है; उसके बाद वह “डेड लेटर” में चली जाती है और फिर नहीं भेजी जा सकती

#डैशबोर्ड में डिलीवरी

“डिलीवरी” किसी webhook का लॉग खोलता है। इसमें तीन टैब हैं:

“सभी डिलीवरी”

सभी डिलीवरी, इवेंट, स्थिति (“सफल (2xx)”, “क्लाइंट त्रुटि (4xx)”, “सर्वर त्रुटि (5xx)”, “विफल”) और “सीमा” के फ़िल्टर के साथ। “↺ फिर कोशिश करें” किसी विफल डिलीवरी को फिर भेजता है, जब तक कोई बाद की सफल डिलीवरी न हो। किसी पंक्ति पर क्लिक करने से अनुरोध, जवाब, बॉडी और raw JSON दिखते हैं।

“रीप्ले”

दोबारा भेजी गई डिलीवरी की शृंखलाएँ, “ठीक हो गया” या “अभी भी विफल” नतीजे और कोशिशों की संख्या के साथ।

“डेड लेटर”

वे डिलीवरी जिनमें हर अनुमत कोशिश विफल रही – पहली डिलीवरी और दोबारा भेजी गई मिलाकर। यह टैब सिर्फ़ देखने के लिए है: इन्हें अब दोबारा नहीं भेजा जा सकता। अपना एंडपॉइंट जाँचें; उसके बाद नए इवेंट सामान्य रूप से डिलीवर होते हैं। अगर आपको डेटा चाहिए, तो उसे API से लें।

अगर कोई दोबारा डिलीवरी नहीं होती, तो डैशबोर्ड कारण बताता है:

“दोबारा नहीं भेजा गया: यह इवेंट पहले ही … बार विफल हो चुका है, और प्रयास संभव नहीं हैं। आप इसे ‘डेड लेटर’ में पाएँगे।”

सभी 3 कोशिशें इस्तेमाल हो चुकी हैं।

“दोबारा नहीं भेजा गया: यह इवेंट इस बीच सफलतापूर्वक पहुँच चुका है।”

उसी शृंखला की कोई बाद की डिलीवरी पहले ही सफल हो चुकी है।

#डैशबोर्ड में सत्यापन

“सत्यापन” के तहत आपको दो मदद मिलती हैं:

“सत्यापन किट”

“किट लोड करें” एल्गोरिदम, हेडर के नाम, साइन किए गए संदेश का फ़ॉर्मैट और 300 सेकंड की सुझाई गई छूट दिखाता है। Secret ख़ुद इसमें शामिल नहीं होता।

“सिग्नेचर सत्यापित करें”

आपको मिली किसी डिलीवरी की delivery ID, timestamp, सिग्नेचर और raw अनुरोध बॉडी डालें। तब LinkHarbor बताता है “सिग्नेचर मान्य है” या “सिग्नेचर अमान्य है”। Timestamp और सिग्नेचर X-LinkHarbor-Timestamp और X-LinkHarbor-Signature हेडर से कॉपी करें। जाँच सिर्फ़ पिछले 5 मिनट की डिलीवरी के लिए काम करती है; पुरानी के लिए यह “सिग्नेचर अमान्य है” बताती है, भले ही सिग्नेचर सही हो।

#Secret बदलना, बंद करना, हटाना

• “Secret ↺” एक नया साइनिंग secret बनाता है और उसे एक बार दिखाता है; पुराना तुरंत काम करना बंद कर देता है, और आपके सर्वर को नया इस्तेमाल करना होगा
• डिलीवरी रोकने के लिए “बदलें” के तहत स्थिति “बंद” पर सेट करें
• कूड़ेदान आइकन webhook हटाता है; संदेश बंद करने तक आप “पूर्ववत करें” से रद्द कर सकते हैं

छोटे प्लान पर जाने पर नई सीमा से ऊपर के webhooks बंद हो जाते हैं, और Creator Free में सभी। ये बने रहते हैं; अपग्रेड के बाद LinkHarbor बंद webhooks को नए प्लान की सीमा तक अपने आप फिर चालू कर देता है – उन्हें भी जो आपने ख़ुद बंद किए थे।