تسجيل الدخولابدأ الفترة التجريبية المجانية
easyCoexistence واجهات API الرسمية

التحقق من خطاف الويب (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 وبسر خاص بتلك الصفحة.

subscribe

القيمة التي يحملها hub.mode دائمًا في طلب التحقق من Meta، أما hub.challenge فهو عدد صحيح يجب إعادته.

sha256=

بادئة X-Hub-Signature-256 تليها توقيع SHA256 تُنشئه Meta من الحمولة ومفتاح App Secret الخاص بالتطبيق.

5 seconds

السرعة التي تردّ بها نقطة نهاية webhook الخاصة بـ Messenger، أي 200 OK، على كل إشعار.

1 hour

عدد عمليات التسليم الفاشلة قبل تنبيه Webhooks Disabled، ثم إلغاء اشتراك التطبيق من الصفحة.

36 hours

المدة التي تعيد فيها 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 الجسم دون تعديل، وهو ما حُسب عليه التوقيع؛ فتحليله أولًا ثم إعادة تسلسله يغيّر البايتات. فيما يلي مثال صغير لنقطة نهاية تستقبل طلب التحقق وتفحص كل طلب يصل إليها:

Python: hub.challenge and X-Hub-Signature-256
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، مع الاحتفاظ بالجسم كبايتات خام:

Node.js: checking X-EC-Signature on a forwarded event
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 ويُفحص بسر توقيع الصفحة.
إنجاز ذلك باستخدام EasyCoexistence

من 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 إلى نقطة النهاية التي حددتها.

تابع القراءة

الاشتراك في خطاف الويب (webhook) لصفحة فيسبوك: الحافة subscribed_appsكيف تشترك صفحة فيسبوك في webhook عبر POST /{page-id}/subscribed_apps: الرموز والمهام، والاشتراك على مستوى التطبيق، والتحقق والإزالة.حقول خطاف الويب (webhook) لصفحات Facebook: القائمة الكاملةالحقول الـ64 لـ webhook صفحات Facebook التي توثّقها Meta: المنشورات والإشارات ورسائل Messenger وحقول الملف الشخصي، وصلاحية كل منها.خطاف الويب (webhook) لـ Messenger في صفحات Facebook: الرسائل وأحداث الإشاراتحقول webhook الخاصة بصفحات Facebook لرسائل Messenger والإشارات: شكل الحمولة ومعرّفات المرسلين والمرفقات، وكيف تصل الأحداث إلى نقطة النهاية الخاصة بك.خطاف الويب (webhook) لـ feed صفحة Facebook: أحداث التعليقات والمنشورات والتفاعلاتما يرسله خطاف feed صفحة Facebook للتعليقات والمنشورات والتفاعلات: حقلا item وverb، وشكل الحمولة في Meta، وكيفية اشتراك الصفحة.رمز الوصول (token) لصفحة Facebook: مدة صلاحيته وما الذي يُبطلهكيف يُحصل على token لصفحة Facebook بلا تاريخ انتهاء، ومن يستطيع ذلك، وما الذي يجعل Meta يتوقف عن قبوله.

اربط قناتك الأولى في دقيقتين.

لا حاجة لانتظار مراجعات المنصات. اربط WhatsApp أو Instagram أو TikTok أو أي قناة أخرى، ثم اطلب من الذكاء الاصطناعي النشر أو الرد أو إعداد التقارير، وشاهده يعمل.

  • 3 أيام مجانًا
  • إلغاء في أي وقت
  • واجهات API الرسمية فقط
  • مراقبة على مدار الساعة 24/7

تم التحقق في