Instagram वेबहुक पुष्टि: hub.challenge और X-Hub-Signature-256
Instagram वेबहुक सेट करने के लिए एक HTTPS एंडपॉइंट चाहिए, जो Meta की पुष्टि वाली GET का जवाब दे। उसमें hub.mode, hub.verify_token और hub.challenge होते हैं। एंडपॉइंट टोकन जाँचकर hub.challenge लौटाता है। फिर, जब ऐप फ़ील्ड की सदस्यता ले ले और हर खाता अपने subscribed_apps एज के ज़रिए सदस्य बन जाए, Meta ऐप के सीक्रेट से हस्ताक्षरित X-Hub-Signature-256 वाले JSON इवेंट POST करता है।
easyCoexistence Meta वाला हिस्सा संभालता है: उसका ऐप पुष्टि पास करता है, X-Hub-Signature-256 जाँचता है, हर जुड़े Instagram खाते को कमेंट, मैसेज और मेंशन की सदस्यता देता है, और इवेंट्स को X-EC-Signature से हस्ताक्षरित करके आपके HTTPS एंडपॉइंट पर भेजता है, हर खाते के लिए अलग सीक्रेट के साथ, और हर कनेक्शन पर चौबीसों घंटे नज़र रखता है।
Meta के पुष्टि अनुरोध में hub.mode का मान हमेशा subscribe होता है।
वह अवधि जिसमें Meta विफल सूचना को घटती आवृत्ति से दोबारा भेजता है, फिर उसे हटा देता है।
विफल मैसेज डिलीवरी की संख्या, जिसके बाद Meta डेवलपर खाते को अलर्ट भेजता है।
विफल मैसेज डिलीवरी की संख्या, जिसके बाद वेबहुक बंद होने का अलर्ट आता है और ऐप खाते से सदस्यता हटा दिया जाता है।
वह ऐप मोड जो Meta माँगता है, इससे पहले कि ऐप अपने उपयोगकर्ताओं के खातों की सूचनाएँ प्राप्त करे।
Instagram वेबहुक सेट करने का तरीका क्या है?
Meta की गाइड जिस क्रम में देती है, उसी क्रम में चार चरण हैं। कोई भी फ़ील्ड चुनने से पहले एंडपॉइंट को पुष्टि पास करनी होगी, उपयोगकर्ताओं के खातों की सूचनाएँ पाने के लिए ऐप को Live होना होगा, और प्रोडक्शन एक्सेस के लिए कारोबार की पुष्टि ज़रूरी है।
पुष्टि अनुरोध में क्या होता है?
कॉलबैक यूआरएल पर एक GET जाता है, जब भी App Dashboard में Webhooks प्रोडक्ट कॉन्फ़िगर होता है। अगर hub.verify_token एंडपॉइंट के अपने टोकन से मेल खाता है, तो जवाब में पूरी बॉडी के रूप में hub.challenge मान के साथ 200 मिलता है; नहीं तो 403। डैशबोर्ड बताता है कि एंडपॉइंट पास हुआ या नहीं।
- hub.mode: हमेशा subscribe।
- hub.challenge: Meta का बनाया एक पूर्णांक, जिसे एंडपॉइंट को वापस भेजना होता है।
- hub.
verify_token: डैशबोर्ड के Verify Token फ़ील्ड में डाली गई स्ट्रिंग, जिसे केवल Meta और एंडपॉइंट को पता होना चाहिए। - PHP में, इन नामों के बिंदु अंडरस्कोर बन जाते हैं, इसलिए मान
hub_mode,hub_challengeऔरhub_verify_tokenके रूप में आते हैं।
GET https://<YOUR_HOST>/webhooks/instagram
?hub.mode=subscribe
&hub.challenge=1158201444
&hub.verify_token=<YOUR_VERIFY_TOKEN>
HTTP/1.1 200 OK
Content-Type: text/plain
1158201444कॉलबैक और फ़ील्ड कहाँ सेट होते हैं?
App Dashboard में, Instagram के अंतर्गत API setup with Instagram login में Configure वेबहुक पर जाएँ: वहाँ कॉलबैक यूआरएल और Verify Token डाले जाते हैं, और सेव करने पर पुष्टि अनुरोध भेजा जाता है। Instagram प्रोडक्ट comments, live_comments, message_reactions, messages, messaging_optins, messaging_postbacks, messaging_referral और messaging_seen की सदस्यता के साथ शुरू होता है, और Manage से इनमें से किसी की भी सदस्यता हटाई जा सकती है। Test बटन चुने गए फ़ील्ड के लिए एक नमूना सूचना भेजता है।
X-Hub-Signature-256 कैसे जाँचा जाता है?
Meta हर इवेंट सूचना के पेलोड का HMAC-SHA256 बनाता है, जिसकी कुंजी ऐप का सीक्रेट होती है, और उसे X-Hub-Signature-256 में sha256= के बाद हेक्स डाइजेस्ट के रूप में भेजता है। प्राप्तकर्ता कच्चे अनुरोध बॉडी पर वही HMAC निकालता है और उसे हेडर से स्थिर समय में तुलना करता है। Meta की मैसेजिंग गाइड बताती है कि हस्ताक्षर Unicode escaped होने के साथ पेलोड पर बनता है, इसलिए डिकोड किए गए या दोबारा सीरियलाइज़ किए गए JSON को हैश करने पर अलग परिणाम आता है।
import crypto from "node:crypto";
import express from "express";
const app = express();
const { VERIFY_TOKEN, APP_SECRET } = process.env;
// Verification request: send hub.challenge back when the token matches
app.get("/webhooks/instagram", (req, res) => {
const ok = req.query["hub.mode"] === "subscribe" &&
req.query["hub.verify_token"] === VERIFY_TOKEN;
if (!ok) return res.sendStatus(403);
res.status(200).type("text/plain").send(req.query["hub.challenge"]);
});
// Event notification: check the signature over the raw bytes
app.post("/webhooks/instagram", express.raw({ type: "application/json" }), (req, res) => {
const expected = Buffer.from(
"sha256=" + crypto.createHmac("sha256", APP_SECRET).update(req.body).digest("hex")
);
const given = Buffer.from(req.get("X-Hub-Signature-256") ?? "");
if (given.length !== expected.length || !crypto.timingSafeEqual(given, expected)) {
return res.sendStatus(401);
}
res.sendStatus(200); // answer first, work after
const body = JSON.parse(req.body.toString("utf8"));
// hand body.entry to a queue or background job
});
app.listen(3000);सिर्फ़ ऐप का सीक्रेट ही इसे क्यों जाँच सकता है?
क्योंकि हस्ताक्षर उसी सीक्रेट से बना HMAC है। उसके बिना कोई अपेक्षित मान नहीं निकाल सकता, और पेलोड की कॉपी रखने वाला भी उसे जाली नहीं बना सकता, इसलिए जाँच उस सर्वर पर होनी चाहिए जो ऐप के लिए Meta के अनुरोध प्राप्त करता है। Meta चाहता है कि ऐप सीक्रेट, एक्सेस टोकन और क्लाइंट क्रेडेंशियल लॉग और सपोर्ट अनुरोधों से बाहर रहें। जो सिस्टम किसी दूसरे ऐप से भेजे गए इवेंट पाता है, वह Meta का हस्ताक्षर बिल्कुल नहीं जाँच सकता, और उसे उस ऐप के अपने हस्ताक्षर पर भरोसा करना पड़ता है।
हर खाते को अपनी सदस्यता क्यों चाहिए?
क्योंकि App Dashboard तय करता है कि ऐप क्या प्राप्त कर सकता है, पर किसी खाते की सूचनाएँ तभी शुरू होती हैं जब वह खाता भी सदस्य बन जाए। Instagram Login के साथ, graph.instagram.com पर POST /<IG_ID>/subscribed_apps भेजें, खाते के Instagram User एक्सेस टोकन के साथ, और subscribed_fields में ऐप के लिए चुने गए फ़ील्ड कॉमा से अलग करके लिखें। सफल कॉल में success का मान true लौटता है।
POST https://graph.instagram.com/<IG_ID>/subscribed_apps
?subscribed_fields=comments,messages
&access_token=<INSTAGRAM_USER_ACCESS_TOKEN>
{ "success": true }डिलीवरी विफल होने पर Meta क्या करता है?
पहले दोबारा भेजता है, फिर छोड़ देता है। Meta की गाइड हर सूचना पर 200 OK माँगती है और चेतावनी देती है कि 1,000 अपडेट तक के बैच की गारंटी नहीं है। विफल अपडेट तुरंत फिर से भेजा जाता है, फिर 36 घंटों में घटती आवृत्ति से कुछ और बार, और उसके बाद छोड़ दिया जाता है, इसलिए एक ही इवेंट दो बार आ सकता है। मैसेजिंग इवेंट Meta के मैसेज डिलीवरी नियमों का पालन करते हैं, जो ज़्यादा तेज़ काम करते हैं:
- 5 सेकंड के भीतर 200 OK अपेक्षित है, और विफल डिलीवरी को कुछ तुरंत रीट्राई मिलते हैं, इसलिए मैसेज के mid पर डुप्लिकेट हटाएँ।
- 15 मिनट की विफलता के बाद डेवलपर खाते को एक अलर्ट जाता है।
- एक घंटे की विफलता के बाद वेबहुक बंद होने का अलर्ट आता है, और ऐप की खाते के वेबहुक से सदस्यता हटा दी जाती है, जब तक वह फिर सदस्य न बने।
- आउटेज के दौरान भेजे गए मैसेज गलत क्रम में आ सकते हैं, इसलिए उन्हें timestamp से क्रमबद्ध करें।
जब कुछ न आए तो क्या जाँचें?
Meta का समस्या-निवारण चेकलिस्ट, जो ज़्यादातर चुप एंडपॉइंट्स को कवर करता है, इस क्रम में:
- कॉलबैक यूआरएल अपनी जाँच पास कर चुका है और वैध सर्टिफ़िकेट के साथ HTTPS पर पहुँच योग्य है; सेल्फ़-साइन्ड सर्टिफ़िकेट समर्थित नहीं हैं।
- ऐप ने फ़ील्ड चुना है और उसके लिए ज़रूरी एक्सेस स्तर है, comments और
live_commentsके लिए Advanced Access। subscribed_appsके ज़रिए खाते के लिए सूचनाएँ सक्षम हैं, और टोकन उसी लॉगिन सेटअप का है।- खाता फ़ील्ड के नियम पूरे करता है: कमेंट सूचनाओं के लिए मीडिया किसी सार्वजनिक खाते का होना चाहिए।
- धीमा काम शुरू करने से पहले सर्वर सफलता लौटाता है।
easyCoexistence Meta के इवेंट को दोबारा साइन क्यों करता है?
क्योंकि Meta का हस्ताक्षर आगे नहीं जा सकता। easyCoexistence का ऐप Meta की डिलीवरी प्राप्त करता है, अपने ही ऐप सीक्रेट से X-Hub-Signature-256 जाँचता है, तुरंत Meta को जवाब देता है, और जुड़े खाते की हर एंट्री को उस खाते के लिए सेट एंडपॉइंट पर भेजता है, एक नए बॉडी में जिसमें platform, account_id, external_id और entry होते हैं। Meta का हेडर आगे नहीं भेजा जाता और उस सीक्रेट के बिना उसकी जाँच भी नहीं हो सकती, इसलिए हर फ़ॉरवर्ड में Content-Type: application/json और X-EC-Signature होता है, जो सिर्फ़ उसी एक खाते के सीक्रेट से बनता है।
X-EC-Signature कैसे जाँचें?
हेडर t=<unix>,v1=<hex> के रूप में होता है, जहाँ v1 टाइमस्टैम्प, एक बिंदु और कच्चे बॉडी का हेक्स HMAC-SHA256 है, जिसकी कुंजी खाते का साइनिंग सीक्रेट है। बाइट्स को जैसे आए वैसे ही उन पर दोबारा गणना करें, स्थिर समय में तुलना करें, और 5 मिनट से पुराने टाइमस्टैम्प को अस्वीकार करें।
- सीक्रेट whsec_ से शुरू होता है और यूआरएल सेट होने पर
set_social_webhook_destinationया PUT /channels/:id/webhook से एक बार दिखाया जाता है। - यूआरएल दोबारा सेट करने पर नया सीक्रेट जारी होता है, और null यूआरएल फ़ॉरवर्डिंग बंद कर देता है।
- हर इवेंट एक बार भेजा जाता है, 8 सेकंड तक इंतज़ार करते हुए, बिना रीडायरेक्ट फ़ॉलो किए, ऐसे HTTPS पते पर जो सार्वजनिक IP पर रेज़ॉल्व होता है।
- कनेक्शन हटाने पर खाते की Meta वेबहुक सदस्यता हट जाती है और उसका एंडपॉइंट व सीक्रेट मिट जाते हैं।
import hashlib, hmac, time
def verify_ec_signature(raw_body: bytes, header: str, secret: str) -> bool:
"""Check X-EC-Signature on an event forwarded by easyCoexistence."""
parts = dict(p.split("=", 1) for p in header.split(",") if "=" in p)
t, v1 = parts.get("t", ""), parts.get("v1", "")
if not t.isdigit() or abs(time.time() - int(t)) > 300:
return False # missing, malformed or older than 5 minutes
expected = hmac.new(secret.encode(), t.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected.encode(), v1.encode())आम गड़बड़ियाँ
- चैलेंज को JSON में या कोट्स में लौटाना। Meta बॉडी के रूप में hub.challenge का मान ही चाहता है, 200 स्टेटस के साथ।
- पार्स किया गया बॉडी हैश करना। JSON बॉडी पार्सर वे सटीक बाइट्स हटा देता है जिन पर Meta ने हस्ताक्षर किया, इसलिए HMAC के लिए कच्चा बॉडी रखें और बाद में पार्स करें।
- ऐप को सदस्य बनाना, पर खाते को भूल जाना। जब तक किसी खाते के लिए POST /<IG_ID>/subscribed_apps सफल नहीं होता, उसके लिए कोई सूचना नहीं आती।
- एंडपॉइंट को एक घंटे तक विफल रहने देना। Meta मैसेजिंग वेबहुक बंद कर देता है और ऐप की खाते से सदस्यता हटा देता है, जिसे फिर से सदस्य बनाना पड़ता है।
set_social_webhook_destination या Partner API से चालू करें। हर कनेक्शन के लिए हर महीने US$ 9 से US$ 0.75 तक, जैसे-जैसे कनेक्शन जुड़ते हैं वैसे घटता हुआ, पहले 3 दिन ट्रायल में मुफ़्त।
अक्सर पूछे जाने वाले सवाल
Instagram वेबहुक में hub.challenge क्या है?
Meta अपनी पुष्टि वाली GET में एक पूर्णांक भेजता है। hub.verify_token जाँचने के बाद एंडपॉइंट उसे जवाब बॉडी के रूप में लौटाता है, जिससे साबित होता है कि यूआरएल पर उसका नियंत्रण है।
PHP में hub.mode और hub.challenge क्यों गायब होते हैं?
PHP पैरामीटर नामों के बिंदुओं को अंडरस्कोर में बदल देता है, इसलिए Meta के पुष्टि मान hub_mode, hub_challenge और hub_verify_token के रूप में आते हैं।
Meta के बंद करने के बाद Instagram वेबहुक दोबारा कैसे चालू करें?
एंडपॉइंट ठीक करें, फिर उसी फ़ील्ड के साथ POST /<IG_ID>/subscribed_apps से खाते की सदस्यता दोबारा लें।
क्या Instagram वेबहुक एंडपॉइंट के लिए सेल्फ़-साइन्ड सर्टिफ़िकेट काम करता है?
नहीं, Meta सेल्फ़-साइन्ड सर्टिफ़िकेट समर्थित नहीं करता: कॉलबैक यूआरएल वैध सर्टिफ़िकेट के साथ HTTPS पर पहुँच योग्य होना चाहिए, जो Meta के समस्या-निवारण चेकलिस्ट का पहला आइटम है।
पढ़ना जारी रखें
दो मिनट में अपना पहला चैनल कनेक्ट करें।
किसी प्लैटफ़ॉर्म की समीक्षा का इंतज़ार नहीं। WhatsApp, Instagram, TikTok या कोई और चैनल कनेक्ट करें, फिर अपने AI से पोस्ट करने, जवाब देने या रिपोर्ट बनाने को कहें और उसे काम करते देखें।
- 3 दिन मुफ़्त
- कभी भी रद्द करें
- सिर्फ़ आधिकारिक एपीआई
- 24/7 निगरानी
इस तारीख को सत्यापित