التحقق من خطاف الويب (webhook) في Instagram: hub.challenge وX-Hub-Signature-256
يتطلب إعداد webhook في Instagram نقطة نهاية (endpoint) تعمل عبر HTTPS وترد على طلب التحقق GET من Meta، الذي يحمل hub.mode بقيمة subscribe وhub.verify_token وhub.challenge، وذلك بفحص الرمز وإعادة قيمة التحدي. ثم ترسل Meta أحداث JSON في طلبات POST موقّعة في X-Hub-Signature-256 بسر التطبيق، بعد أن يشترك التطبيق في الحقول، ويشترك كل حساب عبر حافة subscribed_apps المخصصة له.
يتولى easyCoexistence الجانب الخاص بـ Meta: يجتاز تطبيقه التحقق، ويتحقق من X-Hub-Signature-256، ويشترك كل حساب Instagram مرتبط في comments وmessages وmentions، ويعيد توجيه الأحداث إلى نقطة نهاية HTTPS الخاصة بك موقّعة بـ X-EC-Signature وسر لكل حساب، مع مراقبة كل اتصال على مدار الساعة.
تكون القيمة hub.mode حاضرة دائمًا في طلب التحقق الذي تبعثه Meta إلى الخادم.
المدة التي تعيد Meta خلالها محاولة الإشعار الفاشل بتردد متناقص، قبل أن تتخلى عنه.
عدد عمليات تسليم الرسائل الفاشلة قبل أن ترسل Meta تنبيهًا إلى حساب المطور.
عدد عمليات تسليم الرسائل الفاشلة قبل تنبيه Webhooks Disabled وإلغاء اشتراك التطبيق من الحساب.
وضع التطبيق الذي تشترطه Meta لكي يتلقى التطبيق إشعارات لحسابات مستخدميه.
كيف يعمل إعداد webhook في Instagram؟
في أربع خطوات، بالترتيب الذي يقدمه دليل Meta. يجب أن تجتاز نقطة النهاية التحقق قبل اختيار أي حقل، ويجب أن يكون التطبيق في وضع Live لتلقي الإشعارات لحسابات مستخدميه، والتحقق من الأعمال مطلوب للوصول إلى الإنتاج.
ماذا يحتوي طلب التحقق؟
طلب GET يُرسل إلى callback URL كلما جرى إعداد منتج 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أين تُضبط عنوان الاستدعاء والحقول؟
في لوحة تحكم التطبيق، ضمن Instagram: واجهة برمجة التطبيقات (API) setup with Instagram login، ثم Configure webhooks، وفيها يوضع callback URL و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= متبوعة بالملخص السداسي عشري (hex digest). يحسب المستقبِل HMAC نفسه على نص الطلب الخام، ويقارنه بالترويسة بطريقة زمن ثابت (constant time). وتنبّه وثيقة الرسائل لدى Meta إلى أن التوقيع يغطي الحمولة مع ترميز Unicode كما هو، لذلك فإن تجزئة 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 أصلًا، بل يعتمد على توقيع ذلك التطبيق نفسه.
لماذا يحتاج كل حساب إلى اشتراك خاص به؟
لأن لوحة تحكم التطبيق تحدد ما يستطيع التطبيق استقباله، ولا تبدأ الإشعارات لحساب ما إلا بعد اشتراك ذلك الحساب أيضًا. مع Instagram Login، أرسل POST /<IG_ID>/subscribed_apps إلى graph.instagram.com مع رمز وصول مستخدم Instagram (Instagram User access token)، و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، وهي أسرع في التصرف:
- يُتوقع رد 200 OK خلال 5 ثوانٍ، ويحصل التسليم الفاشل على بضع محاولات فورية، فأزِل التكرار بالاعتماد على معرّف الرسالة (mid).
- بعد 15 دقيقة من الفشل، يُرسل تنبيه إلى حساب المطور.
- بعد ساعة من الفشل، يلي ذلك تنبيه Webhooks Disabled، ويُلغى اشتراك التطبيق في webhooks الحساب حتى يعيد الاشتراك من جديد.
- قد تصل الرسائل المرسلة أثناء الانقطاع خارج ترتيبها، فرتّبها حسب الطابع الزمني.
ماذا يجب أن تفحص عندما لا يصل شيء؟
قائمة Meta لاستكشاف الأخطاء، وهي تغطي معظم نقاط النهاية الصامتة، بهذا الترتيب:
- اجتاز عنوان callback URL فحصه، وهو متاح عبر HTTPS بشهادة صالحة، والشهادات الموقعة ذاتيًا غير مدعومة.
- اختار التطبيق الحقل، ولديه مستوى الوصول اللازم، أي الوصول المتقدم (Advanced Access) في حالة الحقلين comments و
live_commentsتحديدًا. - الإشعارات مفعّلة للحساب عبر
subscribed_apps، مع رمز من إعداد الدخول نفسه. - يستوفي الحساب قواعد الحقل: إشعارات التعليقات تحتاج إلى وسائط مملوكة لحساب عام.
- يُعيد الخادم نجاحًا قبل أن يبدأ أي عمل بطيء.
لماذا يعيد easyCoexistence توقيع الأحداث المُعاد إرسالها؟
لأن توقيع Meta لا يمكن أن ينتقل. يستقبل تطبيق easyCoexistence تسليم Meta، ويتحقق من X-Hub-Signature-256 بسر تطبيقه الخاص، ويرد على Meta فورًا، ثم يرسل بطلب POST كل مدخل لحساب مرتبط إلى نقطة النهاية المحددة لذلك الحساب، داخل جسم جديد يحتوي platform وaccount_id وexternal_id وentry. ولا تُمرَّر ترويسة Meta، ولا يمكن التحقق منها بدون ذلك السر، ولذلك تحمل كل عملية إعادة إرسال Content-Type: application/json وX-EC-Signature، موقّعة بسر يخص ذلك الحساب وحده.
كيف تتحقق من X-EC-Signature؟
تكون الترويسة بالصيغة t=<unix>,v1=<hex>، حيث v1 هو HMAC-SHA256 بترميز hex للطابع الزمني، ثم نقطة، ثم نص الجسم الخام، ومفتاحه سر التوقيع الخاص بالحساب. أعد حسابه على البايتات كما استُلمت تمامًا، وقارنه بطريقة زمن ثابت، وارفض أي طابع زمني أقدم من 5 دقائق.
- يبدأ السر بـ whsec_ ويُعرض مرة واحدة فقط، عبر
set_social_webhook_destinationأو PUT /channels/:id/webhook عند ضبط العنوان. - ضبط العنوان من جديد يصدر سرًا جديدًا، وتعطيل العنوان بقيمة null يوقف إعادة التوجيه.
- يُرسل كل حدث مرة واحدة، مع انتظار حتى 8 ثوانٍ، دون اتباع عمليات إعادة التوجيه، إلى عنوان HTTPS يُحل إلى IP عام.
- إزالة الاتصال تلغي اشتراك الحساب في webhooks لدى 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 webhooks الرسائل وتلغي اشتراك التطبيق من الحساب، فيجب إعادة اشتراكه من جديد.
فعّله عبر set_social_webhook_destination أو Partner API. من US$ 9 إلى US$ 0.75 لكل اتصال شهريًا، وينخفض كلما أضفت اتصالات، مع فترة تجريبية مجانية لمدة 3 أيام.
الأسئلة الشائعة
ما وظيفة hub.challenge في webhook لـ Instagram عند الإعداد؟
عدد صحيح ترسله Meta في طلب GET للتحقق. بعد فحص hub.verify_token تعيده نقطة النهاية كمحتوى للرد، فيثبت أنها تتحكم في العنوان.
لماذا تتغير أسماء hub.mode وhub.challenge عند استخدام PHP في الكود؟
تحوّل PHP النقاط في أسماء المعلمات إلى شرطات سفلية، فتصل قيم التحقق من Meta بالأسماء hub_mode وhub_challenge وhub_verify_token، بدلًا من الأسماء الأصلية.
كيف أعيد تفعيل webhook لحساب Instagram بعد أن عطّلته Meta تلقائيًا؟
أصلح نقطة النهاية أولًا، ثم أعد اشتراك الحساب عبر POST /<IG_ID>/subscribed_apps بالحقول نفسها.
هل تقبل نقطة نهاية webhook الخاصة بـ Instagram شهادة موقعة ذاتيًا؟
لا، إذ لا تدعم Meta الشهادات الموقعة ذاتيًا، ويجب أن يكون عنوان callback URL متاحًا عبر HTTPS بشهادة صالحة، وهذا هو البند الأول في قائمة Meta لاستكشاف الأخطاء.
تابع القراءة
اربط قناتك الأولى في دقيقتين.
لا حاجة لانتظار مراجعات المنصات. اربط WhatsApp أو Instagram أو TikTok أو أي قناة أخرى، ثم اطلب من الذكاء الاصطناعي النشر أو الرد أو إعداد التقارير، وشاهده يعمل.
- 3 أيام مجانًا
- إلغاء في أي وقت
- واجهات API الرسمية فقط
- مراقبة على مدار الساعة 24/7
تم التحقق في