التحقق من خطاف الويب (webhook) في Facebook: hub.challenge و X-Hub-Signature-256
يتحقق Facebook من نقطة النهاية (endpoint) الخاصة بـ webhook بطلب GET يحمل hub.mode بقيمة subscribe وhub.verify_token وhub.challenge؛ تقارن نقطة النهاية verify_token بالقيمة المسجلة في لوحة تحكم التطبيق، وتعيد hub.challenge بوصفه نص الرد. بعد ذلك يصل كل حدث كطلب POST موقّع في X-Hub-Signature-256 بالصيغة sha256= متبوعةً بتوقيع HMAC-SHA256 للحمولة، يُحسب بمفتاح App Secret الخاص بالتطبيق.
يتولى easyCoexistence جانب Meta لكل صفحة تربطها: يجيب تطبيقه على hub.challenge، ويفحص X-Hub-Signature-256، ويشترك في تغذية الصفحة والرسائل والإشارات، ثم يعيد توجيه الأحداث إلى نقطة النهاية HTTPS الخاصة بك موقّعةً بـ X-EC-Signature وبسر خاص بتلك الصفحة.
القيمة التي يحملها hub.mode دائمًا في طلب التحقق من Meta، أما hub.challenge فهو عدد صحيح يجب إعادته.
بادئة X-Hub-Signature-256 تليها توقيع SHA256 تُنشئه Meta من الحمولة ومفتاح App Secret الخاص بالتطبيق.
السرعة التي تردّ بها نقطة نهاية webhook الخاصة بـ Messenger، أي 200 OK، على كل إشعار.
عدد عمليات التسليم الفاشلة قبل تنبيه Webhooks Disabled، ثم إلغاء اشتراك التطبيق من الصفحة.
المدة التي تعيد فيها Meta محاولة إشعار الصفحة الفاشل بتكرار متناقص، قبل إسقاطه.
ماذا يتضمن طلب التحقق من Meta؟
طلب GET يُرسل إلى عنوان URL الخاص بالاستدعاء كلما أُعدّ منتج Webhooks في لوحة تحكم التطبيق، أو أُنشئ اشتراك عبر /{app-id}/subscriptions. يأتي معه ثلاثة معاملات في سلسلة الاستعلام:
- hub.mode: القيمة subscribe دائمًا.
- hub.challenge: عدد صحيح يجب على نقطة النهاية إعادته.
- hub.
verify_token: النص الذي يُدخل في حقل Verify Token في لوحة تحكم التطبيق. - PHP يحوّل النقاط إلى شرطات سفلية، فيقرؤها بوصفها
hub_modeوhub_challengeوhub_verify_token
كيف ينبغي لنقطة النهاية أن ترد عليه؟
برد 200 يكون نصه كله هو قيمة hub.challenge، لكن فقط عندما تكون hub.mode هي subscribe ويتطابق hub.verify_token؛ وأي حالة أخرى تحصل على 403، كما في تطبيق Meta النموذجي. تُظهر لوحة تحكم التطبيق ما إذا نجحت نقطة النهاية، ويُرجع /{app-id}/subscriptions نجاحًا أو خطأً. تحتاج نقطة النهاية إلى HTTPS مع شهادة TLS أو SSL صالحة، لأن الشهادات الموقّعة ذاتيًا غير مدعومة.
كيف تُحسب قيمة X-Hub-Signature-256 في الترويسة؟
هو HMAC-SHA256 لحمولة الطلب، مفتاحه App Secret الخاص بالتطبيق، ويُكتب بالترميز السداسي عشري بحروف صغيرة بعد sha256=. يضيف دليل Meta لـ Messenger أن التوقيع يغطي الحمولة مع ترميز Unicode في صيغة هروب، فالسلسلة مثل äöå تُحسب كأنها \u00e4\u00f6\u00e5: احسب التوقيع على الجسم الخام كما وصل تمامًا، لا على نسخة مفكوكة أو مُعاد تسلسلها. تقول Meta إن التحقق من التوقيع اختياري، لكنها توصي به بشدة.
كيف تتحقق منه في الكود؟
احتفظ بالبايتات الخام، واحسب HMAC، وقارن بزمن ثابت، ثم حلّل. تعيد get_data في Flask الجسم دون تعديل، وهو ما حُسب عليه التوقيع؛ فتحليله أولًا ثم إعادة تسلسله يغيّر البايتات. فيما يلي مثال صغير لنقطة نهاية تستقبل طلب التحقق وتفحص كل طلب يصل إليها:
import hashlib, hmac, os
from flask import Flask, abort, request
app = Flask(__name__)
VERIFY_TOKEN = os.environ["VERIFY_TOKEN"]
APP_SECRET = os.environ["APP_SECRET"].encode()
@app.get("/webhooks/facebook")
def verify():
token = request.args.get("hub.verify_token", "")
if request.args.get("hub.mode") == "subscribe" and hmac.compare_digest(token.encode(), VERIFY_TOKEN.encode()):
return request.args.get("hub.challenge", ""), 200
abort(403)
@app.post("/webhooks/facebook")
def receive():
raw = request.get_data() # the bytes Meta signed
expected = "sha256=" + hmac.new(APP_SECRET, raw, hashlib.sha256).hexdigest()
if not hmac.compare_digest(expected.encode(), request.headers.get("X-Hub-Signature-256", "").encode()):
abort(401)
# answer at once; hand request.get_json() to a queue for the work
return "EVENT_RECEIVED", 200ماذا تتوقع Meta بعد التحقق؟
رد 200 OK لكل إشعار، خلال 5 ثوانٍ لأحداث Messenger. تجمع Meta حتى 1,000 تحديث في التسليم الواحد دون ضمان لذلك، وتتعامل مع الإخفاقات على النحو التالي:
- إشعارات الصفحة: تُعاد المحاولة فورًا، ثم بضع مرات أخرى بتردد متناقص على مدى 36 ساعة، ثم تُسقط.
- إشعارات Messenger: تُعاد المحاولة بضع مرات فورًا؛ وبعد 15 دقيقة من الإخفاق يصل تنبيه إلى حساب المطوّر.
- بعد ساعة من الإخفاق يصل تنبيه Webhooks Disabled، ويُلغى اشتراك التطبيق من الصفحة حتى يشترك من جديد.
- قد تُسلّم المحاولات المكررة الحدث مرتين وخارج الترتيب، لذا أزل التكرار ورتّب الرسائل بحسب الطابع الزمني.
- لا يمكن الاستعلام عن الإشعارات السابقة لاحقًا، لذا خزّن ما تحتاجه فور وصوله.
كيف يستوفي easyCoexistence فحوص Meta المطلوبة؟
يملك تطبيق Meta الخاص بها عنوان URL واحدًا للاستدعاء لكل صفحة تربطها، وتُجري نقطة النهاية الفحصين بنفسها. تردّ على GET فقط عندما تكون hub.mode هي subscribe ويتطابق Verify Token، مع المقارنة بزمن ثابت، وتُرجع 403 في غير ذلك. تقرأ كل طلب POST كنص خام، وتعيد حساب X-Hub-Signature-256 بـ App Secret الخاص بها، وترفض عدم التطابق بالرد 401، وترد على Meta فورًا، ثم تعالج الحدث بعد الرد.
كيف توقّع easyCoexistence ما تعيد توجيهه؟
بتوقيع خاص بها، لأن ترويسة Meta لا يمكن فحصها إلا بـ App Secret الخاص بـ easyCoexistence، ولا تُمرَّر. يُرسل كل إدخال لصفحة متصلة لها نقطة نهاية محددة بطريقة POST بصيغة JSON، على الشكل {platform, account_id, external_id, entry}، مع ترويسة X-EC-Signature بالصيغة t=<unix>,v1=<hex>، حيث v1 هو HMAC-SHA256 للطابع الزمني ونقطة (.) والجسم الخام، مفتاحه سر التوقيع الخاص بتلك الصفحة:
- يبدأ السر بـ whsec_ ويُعرض مرة واحدة فقط، عبر
set_social_webhook_destinationأو PUT /channels/:id/webhook في Partner API (واجهة برمجة التطبيقات). - إعادة ضبط الرابط تُصدر سرًا جديدًا، وضبطه على null يوقف إعادة التوجيه.
- يُرسل كل توجيه مرة واحدة، مع انتظار حتى 8 ثوانٍ، دون اتباع عمليات إعادة التوجيه، إلى عنوان HTTPS يُحلّ إلى عنوان IP عام.
- لا تُحفظ نسخة من الحدث، فلا يوجد ما يمكن إعادة المحاولة منه.
كيف تتحقق من X-EC-Signature عند وصول الحدث؟
افصل الترويسة إلى t وv1، وارفض الطابع الزمني الذي مضى عليه أكثر من 5 دقائق، ثم أعد حساب HMAC على t ونقطة والجسم الخام بسر توقيع الصفحة، وقارن بزمن ثابت. في Node.js، مع الاحتفاظ بالجسم كبايتات خام:
import crypto from "node:crypto";
import express from "express";
const app = express();
const SECRET = process.env.EC_SIGNING_SECRET; // whsec_..., shown once
app.post("/events/facebook", express.raw({ type: "application/json" }), (req, res) => {
const sig = Object.fromEntries(
String(req.get("X-EC-Signature") ?? "").split(",").map((part) => part.split("="))
);
const fresh = Math.abs(Date.now() / 1000 - Number(sig.t)) <= 300;
const expected = crypto
.createHmac("sha256", SECRET)
.update(Buffer.concat([Buffer.from(`${sig.t}.`), req.body]))
.digest("hex");
const ok = fresh && typeof sig.v1 === "string" && sig.v1.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig.v1));
if (!ok) return res.sendStatus(401);
res.sendStatus(200); // answer first: forwards are not retried
const { platform, account_id, external_id, entry } = JSON.parse(req.body.toString("utf8"));
// queue entry for the work
});الأخطاء الشائعة
- تغليف hub.challenge في JSON أو علامات اقتباس. يجب أن يكون نص الرد 200 هو قيمة التحدي نفسها.
- حساب HMAC بعد محلّل JSON. التحليل ثم إعادة التسلسل يغيّران البايتات، وتوقّع Meta الحمولة مع ترميز Unicode، لذا احسب التوقيع على الجسم الخام.
- تنفيذ العمل قبل الرد. يتوقع Messenger ردًا 200 خلال 5 ثوانٍ، وساعة من الإخفاقات تلغي اشتراك التطبيق من الصفحة.
- فحص توقيع Meta على الأحداث المعاد توجيهها. توقّعها Meta بـ App Secret الخاص بـ easyCoexistence، أما الحدث المعاد توجيهه فيحمل X-EC-Signature ويُفحص بسر توقيع الصفحة.
من US$ 9 إلى US$ 0.75 لكل اتصال شهريًا، ويقل السعر كلما أضفت اتصالات، مع أول 3 أيام مجانًا.
الأسئلة الشائعة
كيف تُحدَّد قيمة verify_token في الإعداد؟
تختارها أنت، وهي النص الذي يُدخل في حقل Verify Token عند إعداد webhooks في لوحة تحكم التطبيق، أو القيمة التي تُرسل باسم verify_token إلى /{app-id}/subscriptions عند إنشاء اشتراك.
هل يمكن اختبار التحقق عبر curl بسطر الأوامر؟
نعم. يرسل دليل Meta لـ Messenger طلب GET يحمل hub.verify_token وhub.challenge=CHALLENGE_ACCEPTED وhub.mode=subscribe، وتعيد نقطة النهاية السليمة القيمة المرسلة في hub.challenge كما هي.
ماذا يحدث إذا فشلت نقطة النهاية لمدة ساعة كاملة؟
يرسل Meta تنبيه Webhooks Disabled ويلغي اشتراك التطبيق من الصفحة. بعد إصلاح نقطة النهاية، أعد الاشتراك في الصفحة عبر subscribed_apps، ثم تحقق من النتيجة.
هل أحتاج إلى تطبيق Meta خاص بي لاستقبال webhooks الخاصة بالصفحات؟
لا مع easyCoexistence. تُسلَّم الأحداث إلى تطبيقه، فيعيد توجيه أحداث كل صفحة موقّعةً بترويسة X-EC-Signature إلى نقطة النهاية التي حددتها.
تابع القراءة
اربط قناتك الأولى في دقيقتين.
لا حاجة لانتظار مراجعات المنصات. اربط WhatsApp أو Instagram أو TikTok أو أي قناة أخرى، ثم اطلب من الذكاء الاصطناعي النشر أو الرد أو إعداد التقارير، وشاهده يعمل.
- 3 أيام مجانًا
- إلغاء في أي وقت
- واجهات API الرسمية فقط
- مراقبة على مدار الساعة 24/7
تم التحقق في