Instagram ওয়েবহুক যাচাইকরণ: hub.challenge ও X-Hub-Signature-256
Instagram ওয়েবহুক সেটআপের জন্য একটি HTTPS এন্ডপয়েন্ট দরকার, যেটি Meta-র যাচাইকরণ GET অনুরোধের উত্তর দেয়। এই অনুরোধে hub.mode সেট করা থাকে subscribe, সঙ্গে থাকে hub.verify_token ও hub.challenge। এন্ডপয়েন্ট টোকেন মিলিয়ে দেখে এবং challenge ফেরত দেয়। অ্যাপ ফিল্ড সাবস্ক্রাইব করার পর, এবং প্রতিটি অ্যাকাউন্ট subscribed_apps এজ দিয়ে সাবস্ক্রাইব হওয়ার পর, Meta অ্যাপের সিক্রেট দিয়ে X-Hub-Signature-256-এ সাইন করা JSON ইভেন্ট POST করে।
easyCoexistence Meta-র দিকটি সামলায়: এর অ্যাপ যাচাইকরণ পাস করে, X-Hub-Signature-256 যাচাই করে, সংযুক্ত প্রতিটি Instagram অ্যাকাউন্টকে comments, messages ও mentions-এ সাবস্ক্রাইব করে, এবং ইভেন্টগুলো X-EC-Signature ও প্রতি অ্যাকাউন্টের আলাদা সিক্রেটসহ সাইন করে আপনার HTTPS এন্ডপয়েন্টে ফরওয়ার্ড করে।
Meta-র যাচাইকরণ অনুরোধে hub.mode মানটি সব সময় থাকে।
ব্যর্থ নোটিফিকেশন বাদ দেওয়ার আগে Meta যে সময়সীমা ধরে ক্রমশ কম ঘনঘন রিট্রাই করে।
Meta ডেভেলপার অ্যাকাউন্টে সতর্কবার্তা পাঠানোর আগে ব্যর্থ মেসেজিং ডেলিভারির সংখ্যা।
Webhooks Disabled সতর্কবার্তা ও অ্যাকাউন্ট থেকে অ্যাপের আনসাবস্ক্রাইব হওয়ার আগে ব্যর্থ মেসেজিং ডেলিভারির সংখ্যা।
ব্যবহারকারীদের অ্যাকাউন্টের নোটিফিকেশন পেতে অ্যাপের যে মোড দরকার।
Instagram ওয়েবহুক সেটআপ কীভাবে কাজ করে?
Meta-র গাইড যে ক্রমে দেয়, সেই ক্রমে চার ধাপে। কোনো ফিল্ড বেছে নেওয়ার আগে এন্ডপয়েন্টকে যাচাইকরণ পাস করতে হয়। ব্যবহারকারীদের অ্যাকাউন্টের নোটিফিকেশন পেতে অ্যাপকে Live হতে হয়, এবং প্রোডাকশন অ্যাক্সেসের জন্য বিজনেস যাচাইকরণ লাগে।
যাচাইকরণ অনুরোধে কী থাকে?
কলব্যাক URL-এ একটি GET অনুরোধ, যা App Dashboard-এ Webhooks প্রোডাক্ট কনফিগার করলেই পাঠানো হয়। hub.verify_token এন্ডপয়েন্টের নিজের টোকেনের সঙ্গে মিললে প্রতিক্রিয়া হয় 200, যার পুরো বডি হলো hub.challenge-এর মান। না মিললে 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 webhooks-এর অধীনে: কলব্যাক URL ও যাচাইকরণ টোকেন সেখানে যায়, আর সেভ করলেই যাচাইকরণ অনুরোধ পাঠানো হয়। 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= এবং তার পরে hex ডাইজেস্টসহ। রিসিভার কাঁচা রিকোয়েস্ট বডির উপর একই HMAC হিসাব করে এবং constant time-এ হেডারের সঙ্গে তুলনা করে। Meta-র মেসেজিং গাইড বলে, সিগনেচারটি Unicode escape-করা পেলোডের উপর হয়, তাই ডিকোড করা বা পুনরায় সিরিয়ালাইজ করা 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 দিয়ে, অ্যাকাউন্টের Instagram User অ্যাক্সেস টোকেন ও অ্যাপের জন্য বেছে নেওয়া ফিল্ডগুলো কমা দিয়ে subscribed_fields-এ দিয়ে graph.instagram.com-এ POST /<IG_ID>/subscribed_apps পাঠান। সফল কলে 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 আবার চেষ্টা করে, তারপর হাল ছেড়ে দেয়। Meta-র গাইড প্রতিটি নোটিফিকেশনে 200 OK চায় এবং সতর্ক করে যে ব্যাচিং, অর্থাৎ সর্বোচ্চ 1,000 আপডেট একসঙ্গে, নিশ্চিত নয়। ব্যর্থ আপডেট সঙ্গে সঙ্গে আবার পাঠানো হয়, তারপর 36 ঘণ্টার মধ্যে ক্রমশ কম ঘনঘন আরও কয়েকবার, এবং তার পর বাদ দেওয়া হয়। তাই একই ইভেন্ট দুবার আসতে পারে। মেসেজিং ইভেন্ট Meta-র মেসেজিং ডেলিভারি নিয়ম মানে, যা দ্রুত কাজ করে:
- 200 OK প্রত্যাশিত 5 সেকেন্ডের মধ্যে, এবং ব্যর্থ ডেলিভারি কয়েকবার তৎক্ষণাৎ রিট্রাই পায়, তাই message mid দিয়ে ডুপ্লিকেট বাদ দিন।
- 15 মিনিট ব্যর্থতার পর ডেভেলপার অ্যাকাউন্টে একটি সতর্কবার্তা যায়।
- এক ঘণ্টা ব্যর্থতার পর Webhooks Disabled সতর্কবার্তা আসে, এবং আবার সাবস্ক্রাইব না করা পর্যন্ত অ্যাপ অ্যাকাউন্টের ওয়েবহুক থেকে আনসাবস্ক্রাইব থাকে।
- আউটেজের সময় পাঠানো মেসেজ ক্রম ছাড়া আসতে পারে, তাই timestamp অনুযায়ী সাজান।
কিছুই না এলে কী যাচাই করবেন?
Meta-র ট্রাবলশুটিং চেকলিস্ট, যা বেশিরভাগ নীরব এন্ডপয়েন্ট ঢাকে, এই ক্রমে:
- কলব্যাক URL যাচাইয়ে পাস করেছে এবং বৈধ সার্টিফিকেটসহ HTTPS-এ পৌঁছানো যায়; self-signed সার্টিফিকেট সমর্থিত নয়।
- অ্যাপ ফিল্ডটি বেছেছে এবং প্রয়োজনীয় অ্যাক্সেস লেভেল আছে, comments ও
live_comments-এর জন্য Advanced Access। subscribed_apps-এর মাধ্যমে অ্যাকাউন্টের জন্য নোটিফিকেশন চালু আছে, একই লগইন সেটআপের টোকেন দিয়ে।- অ্যাকাউন্ট ফিল্ডের নিয়ম মেনে চলে: কমেন্ট নোটিফিকেশনে পাবলিক অ্যাকাউন্টের মালিকানাধীন মিডিয়া লাগে।
- সার্ভার ধীর কাজ শুরু করার আগে success ফেরত দেয়।
easyCoexistence ফরওয়ার্ড করা ইভেন্টে আবার সাইন করে কেন?
কারণ Meta-র সিগনেচার সঙ্গে যেতে পারে না। easyCoexistence-এর অ্যাপ Meta-র ডেলিভারি গ্রহণ করে, নিজের অ্যাপ সিক্রেট দিয়ে X-Hub-Signature-256 যাচাই করে, সঙ্গে সঙ্গে Meta-কে উত্তর দেয়, এবং সংযুক্ত অ্যাকাউন্টের প্রতিটি entry সেই অ্যাকাউন্টের জন্য সেট করা এন্ডপয়েন্টে POST করে। এটি platform, account_id, external_id ও entry-সহ একটি নতুন বডিতে যায়। Meta-র হেডার পাঠানো হয় না, এবং ওই সিক্রেট ছাড়া সেটি যাচাইও করা যেত না। তাই প্রতিটি ফরওয়ার্ডে থাকে Content-Type: application/json এবং X-EC-Signature, যা শুধু ওই একটি অ্যাকাউন্টের সিক্রেট দিয়ে তৈরি।
X-EC-Signature কীভাবে যাচাই করবেন?
হেডারটি এরকম: t=<unix>,v1=<hex>। v1 হলো টাইমস্ট্যাম্প, একটি ডট এবং কাঁচা বডির hex HMAC-SHA256, যা অ্যাকাউন্টের সাইনিং সিক্রেট দিয়ে তৈরি। যেভাবে পৌঁছেছে ঠিক সেই বাইট দিয়ে পুনরায় হিসাব করুন, constant time-এ তুলনা করুন, এবং 5 মিনিটের বেশি পুরনো টাইমস্ট্যাম্প প্রত্যাখ্যান করুন।
- সিক্রেট whsec_ দিয়ে শুরু হয় এবং URL সেট করার সময়
set_social_webhook_destinationবা PUT /channels/:id/webhook দিয়ে একবারই দেখানো হয়। - URL আবার সেট করলে নতুন সিক্রেট ইস্যু হয়, এবং null URL ফরওয়ার্ডিং বন্ধ করে দেয়।
- প্রতিটি ইভেন্ট একবার পাঠানো হয়, 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())সাধারণ ভুলগুলো
- challenge-টি 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 যাচাই করার পর এন্ডপয়েন্ট সেটি প্রতিক্রিয়ার বডি হিসেবে ফেরত দেয়, যা প্রমাণ করে URL-টি তার নিয়ন্ত্রণে আছে।
PHP-তে hub.mode ও hub.challenge নেই কেন?
PHP প্যারামিটারের নামের ডটগুলোকে আন্ডারস্কোর করে দেয়, তাই Meta-র যাচাইকরণ মানগুলো আসে hub_mode, hub_challenge ও hub_verify_token হিসেবে।
Meta নিষ্ক্রিয় করার পর Instagram ওয়েবহুক কীভাবে আবার চালু করব?
এন্ডপয়েন্ট ঠিক করুন, তারপর একই ফিল্ডসহ POST /<IG_ID>/subscribed_apps দিয়ে অ্যাকাউন্টটি আবার সাবস্ক্রাইব করুন।
Instagram ওয়েবহুক এন্ডপয়েন্টে self-signed সার্টিফিকেট কাজ করে?
না, Meta self-signed সার্টিফিকেট সমর্থন করে না। callback URL-কে বৈধ সার্টিফিকেটসহ HTTPS-এ পৌঁছানো যেতে হবে, যা Meta-র ট্রাবলশুটিং চেকলিস্টের প্রথম আইটেম।
আরও পড়ুন
দুই মিনিটে আপনার প্রথম চ্যানেল সংযুক্ত করুন।
প্ল্যাটফর্মের রিভিউয়ের জন্য অপেক্ষা করতে হবে না। WhatsApp, Instagram, TikTok বা অন্য কোনো চ্যানেল সংযুক্ত করুন, তারপর আপনার AI-কে পোস্ট করতে, রিপ্লাই দিতে বা রিপোর্ট দিতে বলুন, আর নিজের চোখে দেখুন কীভাবে কাজ করে।
- 3 দিন ফ্রি
- যেকোনো সময় বাতিল করুন
- শুধুমাত্র অফিশিয়াল API
- 24/7 পর্যবেক্ষণ
যাচাই করা হয়েছে