كيف تستقبل عبر خطاف الويب (webhook) رسائل عملائك على WhatsApp وتعليقات مواقع التواصل
يحصل كل اتصال على webhook خاص به لاستقبال رسائل عملائك على WhatsApp أو تعليقاتهم على منصات التواصل، وذلك عبر Partner API الخاصة بـ easyCoexistence. ترسل رسائل WhatsApp من Meta مباشرة إلى عنوان URL هذا، وتُوقَّع بسر تطبيق Tech Provider لا بسر تحتفظ به أنت، لذلك يوثّقها سر عشوائي طويل ضمن مسار عنوان URL. أما التعليقات والرسائل المباشرة على Instagram وFacebook، وتعليقات TikTok، فتُعاد توجيهها فور وصولها، ويُوقَّع كل حساب منها بترويسة X-EC-Signature الخاصة به.
الحد الأقصى الذي تحدده Meta لطول عنوان URL البديل للاستدعاء الذي يرسل رسائل الرقم إلى نقطة النهاية (endpoint) الخاصة بك.
المدة التي تعيد فيها Meta محاولة تسليم webhook خاص بـ WhatsApp لم يقبله endpoint لديك، بتواتر متناقص، وهو ما قد يتسبب في تكرار الرسائل.
شبكة Meta؛ استعلامات whois عن المسارات تُظهر عناوين IP التي تصل منها webhooks الخاصة بـ WhatsApp، وتغيّرها Meta دوريًا.
أكبر حجم تبلغه حمولة webhook الخاصة بـ WhatsApp، بحسب ما تحدده Meta.
العمر الذي ينبغي بعده رفض الطابع الزمني الموقّع للحدث المعاد توجيهه، مع مقارنة HMAC بزمن ثابت.
كيف يحصل كل اتصال على وجهته الخاصة؟
عبر استدعاء واحد لكل مورد. يُستدعى رقم WhatsApp عبر PUT /connections/{id}/webhook مع url وverify_token، أو عبر الزوج نفسه باسم webhook_url وwebhook_verify_token في جلسة الربط الخاصة به، فيُوجَّه الرقم إليك منذ دقيقته الأولى. ويُستدعى حساب منصة التواصل عبر PUT /channels/{id}/webhook مع url بعد اتصاله. وقيمة url المساوية لـ null في أيٍّ منهما توقف التسليم. يختلف المساران في الجهة التي تسلّم وفي طريقة المصادقة:
| WhatsApp number | Instagram, Facebook, TikTok | |
|---|---|---|
| Set with | webhook_url on the session, or PUT /connections/{id}/webhook | PUT /channels/{id}/webhook, after it connects |
| Delivered by | Meta, straight to your URL | easyCoexistence, forwarding each event as it arrives |
| Body | Meta's webhook, unchanged | platform, account_id, external_id and the network's entry |
| Authenticate | A long random secret in the URL path | X-EC-Signature, keyed with the account's secret |
| Retries | Meta's own, for up to 7 days | None: one attempt |
| Copy kept | None | None |
كيف توجّه رسائل الرقم إلى نقطة النهاية الخاصة بك؟
امنحه عنوان URL عبر HTTPS يحمل في مساره سرًا عشوائيًا طويلًا، مع رمز تحقق (verify token): webhook_verify_token في جلسة الربط، بطول من 8 إلى 200 حرف، أو verify_token في طلب PUT. تتحقق Meta من العنوان فورًا بطلب GET يحمل hub.mode=subscribe وhub.verify_token وhub.challenge، ويجب أن ترد نقطة النهاية لديك بقيمة hub.challenge حين يتطابق الرمز. إذا فشلت هذه المصافحة، يعيد طلب PUT استجابة 502 بالرمز meta_rejected مع رسالة Meta نفسها؛ وفي جلسة الربط يبقى الرقم متصلًا، لكن last_error في الجلسة يوضح السبب الذي من أجله لم يُطبَّق عنوان URL.
import express from "express";
import { timingSafeEqual } from "node:crypto";
const PATH_SECRET = process.env.WA_PATH_SECRET; // the random part of webhook_url
const VERIFY_TOKEN = process.env.WA_VERIFY_TOKEN; // the verify token you sent
const app = express();
function same(a, b) {
const x = Buffer.from(String(a)), y = Buffer.from(String(b));
return x.length === y.length && timingSafeEqual(x, y);
}
// Meta's handshake, run when the destination is set
app.get("/wa/:secret", (req, res) => {
if (!same(req.params.secret, PATH_SECRET)) return res.sendStatus(404);
if (req.query["hub.mode"] !== "subscribe" || !same(req.query["hub.verify_token"], VERIFY_TOKEN)) {
return res.sendStatus(403);
}
res.send(req.query["hub.challenge"]);
});
// Messages, echoes and the one-time import; payloads reach 3 MB
app.post("/wa/:secret", express.json({ limit: "4mb" }), (req, res) => {
if (!same(req.params.secret, PATH_SECRET)) return res.sendStatus(404);
res.sendStatus(200); // answer first: Meta retries for up to 7 days
enqueue(req.body); // deduplicate on each message id before acting
});لماذا لا يمكنك التحقق من توقيع Meta، وبماذا يُستعاض عنه؟
توقّع Meta كل تسليم بـ X-Hub-Signature-256، وهو HMAC-SHA256 للحمولة بمفتاح App Secret الخاص بالتطبيق المستقبِل. وبالنسبة إلى أرقام عملائك يكون ذلك التطبيق هو تطبيق Tech Provider الخاص بـ easyCoexistence، ولا يُشارَك سره أبدًا، فلا يمكن التحقق من الترويسة من جهتك. يكون السر العشوائي الطويل في مسار عنوان URL بديلًا عن ذلك كبيانات اعتماد: قارنه بزمن ثابت وارفض ما عداه. وكطبقة ثانية، أدرج في قائمة السماح المسارات المسجّلة لدى Meta ضمن AS32934 وحدّثها، لأن Meta تغيّر عناوين IP الخاصة بها بين حين وآخر.
أيّ webhooks خاصة بـ WhatsApp تصل إلى عنوان URL الخاص بك؟
الحقول التي يحملها عنوان URL البديل للاستدعاء في Meta: messages، لما يرسله العملاء وحالة ما ترسله أنت؛ وsmb_message_echoes، لما يرسله النشاط التجاري من تطبيق WhatsApp Business؛ وhistory وsmb_app_state_sync الخاصان بالاستيراد لمرة واحدة. لا ترسل Meta أبدًا webhooks القوالب ولا webhooks الحساب مثل account_update إلى الاستبدال، بل تصل إلى استدعاء easyCoexistence، ولهذا تُقرأ مراجعة القالب بالاستطلاع، ويصلك الإسقاط كحدث حالة.
- تُضبط الوجهة على حساب WhatsApp Business، فيشترك رقمان في الحساب الواحد في الوجهة نفسها، لذا وجّه الرسائل استنادًا إلى value.metadata.
phone_number_idفي الحمولة. - تصل الوسائط كمعرّف، فاجلب الملف من Meta باستخدام token العميل من استدعاء بيانات الاعتماد.
- قد تبلغ الحمولات 3 MB، فارفع أي حد لحجم الجسم مضبوط أقل من ذلك.
كيف يبدو الحدث المعاد توجيهه من منصة التواصل؟
طلب POST بـ Content-Type يساوي application/json وترويسة X-EC-Signature، ويحمل أربعة مفاتيح: platform؛ وaccount_id، وهو معرّف القناة في Partner API؛ وexternal_id، وهو معرّف الحساب على الشبكة؛ وentry. في Instagram وFacebook يبقى entry هو مدخل webhook من Meta دون أي تغيير، مع changes للتعليقات والإشارات وmessaging للرسائل المباشرة. أما TikTok فيحمل حدث comment.update بمحتواه مُحلَّلًا، وcomment_id وvideo_id وparent_comment_id كنصوص، حتى لا تُقرَّب المعرّفات ذات 64 بت.
- تشترك حسابات Instagram في التعليقات والرسائل والإشارات، وصفحات Facebook في feed وmessages وmention، وفي TikTok يُرسل الحدث comment.update فقط.
- لا تستقبل easyCoexistence أي أحداث تعليقات من YouTube أو LinkedIn: تُعيد PUT الخاصة بهما الاستجابة 400 بالرمز
not_supported، وتُقرأ تعليقاتهما عبر واجهة كل شبكة باستخدام بيانات الاعتماد. - لا تحمل الأحداث المعاد توجيهها ترويسة X-EC-Event أو X-EC-Delivery، لذا أزل التكرار بالاعتماد على معرّفات الشبكة نفسها، مثل معرّف التعليق أو mid الرسالة.
{
"platform": "instagram",
"account_id": "<CHANNEL_ID>",
"external_id": "<INSTAGRAM_ACCOUNT_ID>",
"entry": {
"id": "<INSTAGRAM_ACCOUNT_ID>",
"time": 1793440800,
"changes": [
{
"field": "comments",
"value": {
"id": "<COMMENT_ID>",
"from": { "id": "<INSTAGRAM_SCOPED_ID>", "username": "<USERNAME>" },
"text": "<COMMENT_TEXT>",
"media": { "id": "<MEDIA_ID>", "media_product_type": "<MEDIA_PRODUCT_TYPE>" }
}
}
]
}
}كيف تتحقق من X-EC-Signature خطوة بخطوة؟
باستخدام signing_secret الذي أعاده PUT /channels/{id}/webhook، ويظهر مرة واحدة فقط، وهو فريد لذلك الحساب. تكون الترويسة بالصيغة t=<unix>,v1=<hex>. ثم، لكل تسليم:
- قبل أي تحليل، اقرأ جسم الطلب الخام كبايتات.
- افصل الترويسة عند الفواصل إلى t، وهو زمن Unix بالثواني، وv1، وهو ملخص بالنظام السداسي العشري.
- ارفض التسليم إذا كان الزمن t يبعد أكثر من 5 دقائق عن ساعتك.
- احسب HMAC-SHA256 على t، ثم نقطة، ثم الجسم الخام، بمفتاح سر ذلك الحساب، واكتبه بالنظام السداسي العشري.
- قارنه مع v1 بزمن ثابت، ثم أرسل استجابة 2xx وضع العمل في قائمة الانتظار.
import express from "express";
import { createHmac, timingSafeEqual } from "node:crypto";
const app = express();
const secrets = new Map(); // channel id -> signing_secret, kept in your database
app.post("/hooks/social", express.raw({ type: "application/json" }), (req, res) => {
const sig = Object.fromEntries(
(req.get("X-EC-Signature") ?? "").split(",").map((part) => part.split("=", 2)),
);
if (!/^\d+$/.test(sig.t ?? "") || Math.abs(Date.now() / 1000 - Number(sig.t)) > 300) {
return res.sendStatus(401); // missing or stale timestamp
}
let event;
try {
event = JSON.parse(req.body.toString("utf8")); // platform, account_id, external_id, entry
} catch {
return res.sendStatus(400);
}
const secret = secrets.get(event.account_id);
if (!secret || !sig.v1) return res.sendStatus(401);
const expected = createHmac("sha256", secret)
.update(sig.t + ".")
.update(req.body) // the raw bytes, exactly as they arrived
.digest("hex");
if (expected.length !== sig.v1.length ||
!timingSafeEqual(Buffer.from(expected), Buffer.from(sig.v1))) {
return res.sendStatus(401);
}
res.sendStatus(204); // one attempt and no retries: acknowledge, then work
enqueue(event);
});ماذا يحدث حين لا تكون الوجهة مضبوطة؟
لا يصلك شيء، ولا يُحتفظ بشيء ليُرسل لاحقًا. يُحوَّل الرقم الذي لا يملك webhook_url إلى استدعاء easyCoexistence، فتُسقط رسائله دون حفظ، ولا يحصل على استيراد لسجل المحادثات، إذ يُطلب الاستيراد فقط بعد وجود وجهة. أما حساب منصة التواصل بلا وجهة فلا تُعاد توجيه أحداثه: تصل إلى تطبيق easyCoexistence، لكن لا يُحتفظ بأي منها لك. اضبط كل وجهة قبل أن تحتاج إلى حركة المرور.
ماذا يحدث للوجهة عندما ينقطع الاتصال أو يُزال؟
يحتفظ الرقم بوجهته في السجل. عندما يعود رقم انقطع إلى الاتصال، تعيد easyCoexistence ضبط عنوان URL لديك مع Meta، ويحدث الشيء نفسه عند عودة رقم موقوف. أما إزالة حساب منصة التواصل فتمحو وجهته وسره، لذا بعد إعادة اتصاله استدعِ PUT /channels/{id}/webhook مرة أخرى واحفظ السر الجديد. ويُصدر ذلك الطلب سرًا جديدًا كلما استُدعي مع عنوان URL، ويتوقف السر القديم عن التوقيع فورًا.
كيفية إعداده
- Put a secret in the URLChoose an HTTPS URL whose path holds a long random string, 200 characters or fewer in all, and make its GET answer Meta's hub.challenge.
- Route the number's messagesSend webhook_url and webhook_verify_token on the connect session, or PUT /connections/{id}/webhook once the number is connected.
- Turn on each social accountCall PUT /channels/{id}/webhook with your URL and store the signing_secret it returns against that channel.
- Verify, then acknowledgeCheck the path secret on WhatsApp deliveries and X-EC-Signature on forwarded ones, answer 2xx at once, then process from a queue.
الأخطاء الشائعة
- التحقق من X-Hub-Signature-256 في تسليمات WhatsApp لعملائك. تحسبه Meta بسر تطبيق easyCoexistence الذي لا يُشارَك أبدًا، لذا لن ينجح الفحص. صادِق بالسر الموجود في مسار عنوان URL بدلًا منه.
- التحقق من X-EC-Signature على JSON بعد تحليله. يغطي HMAC الجسم الخام بايتًا بايتًا، وإعادة تسلسله تغيّر البايتات، لذا تحقّق قبل التحليل.
- استخدام سر واحد لكل قناة. يوقّع كل حساب منصة بسره الخاص، وتوقّع أحداث الحالة بسر آخر، فابحث عن السر المناسب بالاعتماد على account_id الخاص بالحدث.
- إجراء عمل بطيء قبل الرد على حدث معاد توجيهه. يُرسل مرة واحدة، ويمهلك 8 ثوانٍ لتجيب، ولا يُعاد إرساله أبدًا، لذا أرسل استجابة 2xx أولًا ثم عالج لاحقًا.
تُوجّه easyCoexistence رسائل كل رقم عميل من Meta مباشرة إلى خادمك، وتُعيد توجيه تعليقات Instagram وFacebook ورسائلهما المباشرة، وتعليقات TikTok، إلى نقطة النهاية الخاصة بك فور وصولها، موقّعة لكل حساب، دون الاحتفاظ بأي نسخة، ومع مراقبة كل اتصال على مدار الساعة. من US$ 9 إلى US$ 0.75 لكل اتصال شهريًا، ويقل السعر كلما أضفت اتصالات، مع فترة تجريبية مجانية مدتها 3 أيام.
الأسئلة الشائعة
هل يمكنني التحقق من توقيع Meta على رسائل WhatsApp لعملائي؟
لا. توقّعها Meta بسر تطبيق Tech Provider الخاص بـ easyCoexistence، ولا يُشارَك هذا السر أبدًا. وثّق باستخدام السر العشوائي الطويل في مسار عنوان URL لديك، ويمكنك اختياريًا التحقق من نطاقات عناوين IP التي تعود لها.
هل تُعاد توجيه أحداث التعليقات من اتصالات YouTube وLinkedIn؟
لا. لا تستقبل easyCoexistence أي أحداث تعليقات من أيٍّ منهما، لذا يُجيب PUT /channels/{id}/webhook بالرمز 400 not_supported. اقرأ تعليقاتهما عبر واجهة كل شبكة باستخدام بيانات اعتماد القناة.
هل تُعاد محاولة الأحداث المعاد توجيهها من منصات التواصل إذا كان خادمي متوقفًا؟
لا. يُرسل كل حدث مرة واحدة دون الاحتفاظ بنسخة منه. تختلف تسليمات WhatsApp، لأن Meta نفسها تعيد محاولتها لمدة تصل إلى 7 أيام.
هل تمر الرسائل عبر easyCoexistence؟
لا على WhatsApp: تسلّم Meta رسائل الرقم مباشرة إلى webhook الذي ضبطته. أما التعليقات والرسائل المباشرة من منصات التواصل فتُعاد توجيهها إلى نقطة النهاية لديك فور وصولها، موقّعة لكل حساب، دون الاحتفاظ بأي نسخة.
تابع القراءة
اربط قناتك الأولى في دقيقتين.
لا حاجة لانتظار مراجعات المنصات. اربط WhatsApp أو Instagram أو TikTok أو أي قناة أخرى، ثم اطلب من الذكاء الاصطناعي النشر أو الرد أو إعداد التقارير، وشاهده يعمل.
- 3 أيام مجانًا
- إلغاء في أي وقت
- واجهات API الرسمية فقط
- مراقبة على مدار الساعة 24/7
تم التحقق في