بناء بوت واتساب بـ n8n — الويب هوك والأمان

هذه هي الحلقة الأولى من سلسلة بناء بوت واتساب احترافي باستخدام n8n. في هذه الحلقة نضع الأساس الكامل: ويب هوك الاستقبال والتحقق، تنظيف الرسائل الواردة وتوحيدها، وطبقة أمان كاملة بتوقيع HMAC-SHA256 — بالضبط كما تشترطه Meta لأي بوت في بيئة الإنتاج.

إذا كنت تريد فهم كيفية إعداد الـ Webhook مع Meta قبل البدء، شاهد هذا الفيديو أولاً: إعداد Webhook الواتساب مع Meta. وإذا أردت التعمق في طبقات الأمان التي نبنيها هنا، اقرأ مقالنا: 5 طبقات أمان لازم تكون في أي بوت واتساب.

ما الذي نبنيه في هذه الحلقة؟

الـ workflow الذي نبنيه يتكون من المراحل التالية:

ويب هوك GET للتحقق من الـ Webhook مع Meta
ويب هوك POST لاستقبال الرسائل الواردة
نود تنظيم الرسائل وتوحيدها (Extract & Normalize)
IF node لتصفية الـ Status Webhooks
Security: Prepare Webhook Data — تجهيز البيانات للتحقق
Crypto node — حساب توقيع HMAC-SHA256
Security: Compare & Validate — مقارنة التوقيعات
IF node للتحقق من نجاح فحص الأمان قبل المتابعة

الجزء الأول: الويب هوك (0:00 – 0:40)

لماذا نحتاج ويب هوكَين وليس واحداً؟

كثير من المبتدئين يبدأون بويب هوك POST واحد ويتساءلون لماذا لا يعمل التحقق مع Meta. السبب: Meta ترسل طلب GET أولاً للتحقق من أن عنوان الويب هوك صحيح وأنت تتحكم فيه — وهذا الطلب مختلف تماماً عن رسائل الواتساب التي تصل عبر POST.

الإعداد الصحيح يتطلب:

Webhook GET: يستقبل طلب التحقق من Meta ويرد بـ hub.challenge
Webhook POST: يستقبل الرسائل والأحداث الواردة من واتساب
Respond to Webhook: نود منفصل لكل فرع للرد الفوري على Meta

⚠️ للإعداد التفصيلي للـ Webhook مع Meta، شاهد: فيديو إعداد الـ Webhook.

الجزء الثاني: Extract & Normalize Message (0:41 – 0:50)

لماذا نحتاج هذا النود؟

البيانات التي تصل من Meta مدمجة في JSON متداخل ومعقد. إذا تعاملنا مع هذا الـ payload مباشرة في كل نود لاحق، سيصبح الـ workflow هشاً وصعب الصيانة. نود الـ Normalize يحول هذا:

entry[0].changes[0].value.messages[0].text.body

إلى هذا:

{
  "sender_id": "966XXXXXXXXX",
  "text": "مرحبا",
  "type": "text",
  "timestamp": 1715000000000,
  "message_id": "wamid.XXX",
  "conversation_id": "966XXXXXXXXX_1234567890",
  "attachment_type": null,
  "media_id": null
}

كل الـ nodes اللاحقة تتعامل مع بيانات نظيفة وموحدة بدلاً من الـ raw payload. النود يدعم أيضاً أنواع الرسائل المختلفة: نص، صور، فيديو، صوت، مستندات، وموقع جغرافي.

📥 تحميل كود Extract & Normalize: اضغط هنا لتحميل الكود

الجزء الثالث: IF Node — تصفية Status Webhooks (1:01 – 1:36)

ما هي الـ Status Webhooks؟

Meta لا ترسل فقط الرسائل الواردة — بل ترسل أيضاً إشعارات عن حالة الرسائل التي أرسلتها أنت: تم الإرسال، تم التوصيل، تم القراءة. هذه تصل كـ statuses في الـ payload وليس كـ messages.

الـ IF node يتحقق: هل يوجد error: true في ناتج نود الـ Normalize؟

True (خطأ): Status update أو حدث غير مدعوم — يذهب لـ NoOp وينتهي بهدوء
False (رسالة حقيقية): يكمل لطبقة الأمان

NoOp مقابل Stop & Error: في بيئة الإنتاج نفضل NoOp لأن Stop & Error يسجّل الحادثة كخطأ في سجلات n8n مما يصعّب تمييز الأخطاء الحقيقية. الـ Status webhooks أمر طبيعي ومتوقع وليس خطأ.

الجزء الرابع: Security — Prepare Webhook Data (1:50 – 2:24)

لماذا نحتاج هذا النود قبل الـ Crypto؟

قبل أن نتحقق من التوقيع، نحتاج تجهيز البيانات الصحيحة. نود الـ Code يقوم بـ:

استخراج التوقيع الوارد من Meta من الـ header: x-hub-signature-256
إعادة تسلسل الـ raw body كنص JSON لإعادة حسابه
تمرير كل الحقول المطلوبة لنود الـ Crypto و Compare & Validate
التحقق من test mode — لو الرسالة من بيئة اختبار يتجاوز التحقق تلقائياً

📥 تحميل كود Security: Prepare Webhook Data: اضغط هنا لتحميل الكود

الجزء الخامس: Crypto Node — حساب HMAC (2:26 – 2:51)

نود الـ Crypto المدمج في n8n يحسب HMAC-SHA256 للـ body باستخدام الـ App Secret الخاص بتطبيقك في Meta. الناتج يكون توقيعاً رقمياً نقارنه بالتوقيع الوارد من Meta.

⚠️ الـ App Secret سري للغاية — لا تكتبه مباشرة في الـ node. استخدم n8n Credentials لتخزينه بأمان. في الفيديو قطعنا هذا الجزء عمداً لأسباب أمنية — للتفاصيل شاهد فيديو إعداد الـ Webhook الذي يشرح كيفية الحصول على الـ App Secret من لوحة Meta.

الجزء السادس: Security — Compare & Validate (3:15 – 4:05)

نود Code أخير يقارن التوقيع المحسوب بالتوقيع الوارد من Meta. لكنه لا يكتفي بمقارنة التوقيع فقط — بل يتحقق أيضاً من:

توقيع HMAC-SHA256: التوقيع المحسوب يطابق الوارد من Meta
الحقول الأساسية: sender_id، conversation_id، message_id، timestamp موجودة
صحة الـ sender_id: يجب أن يكون رقماً فقط
الـ Timestamp: الرسالة ليست أقدم من 5 دقائق ولا من المستقبل (clock skew detection)

إذا تطابق كل شيء — الرسالة أصلية وتكمل. إذا فشل أي فحص — يُرفض الطلب مع تسجيل سبب الرفض بدقة.

📥 تحميل كود Security: Compare & Validate: اضغط هنا لتحميل الكود

الجزء السابع: IF Node — هل نجح فحص الأمان؟ (4:05 – 4:59)

بعد الـ Compare & Validate، يأتي IF node يتحقق من قيمة passed:

True (نجح): الرسالة أصلية — تكمل معالجتها وترد على المستخدم
False (فشل): الطلب مشبوه — يُرفض مع تسجيل rejection_category و rejection_detail

هذا الـ IF node هو البوابة الأخيرة قبل أن تصل الرسالة إلى منطق الرد. لا شيء يمر بدون هوية مؤكدة.

ملخص الأكواد المستخدمة في الحلقة

النود	الوظيفة	التحميل
Extract & Normalize	تحويل الـ raw payload إلى بيانات نظيفة	تحميل
Prepare Webhook Data	استخراج التوقيع وتجهيز الـ body للـ HMAC	تحميل
Compare & Validate	مقارنة التوقيعات والتحقق من صحة الحقول	تحميل

ما الذي نبنيه في الحلقة الثانية؟

في الحلقة القادمة نتعمق في Supabase — نصمم قاعدة البيانات الكاملة للبوت: جداول المستخدمين، المحادثات، الرسائل، وإدارة الجلسات. هذا هو الأساس الذي يجعل البوت يتذكر السياق ويتعامل مع محادثات متعددة في نفس الوقت.

تابع القناة حتى لا تفوتك الحلقة الثانية.

روابط مفيدة

الأسئلة الشائعة

لماذا نستخدم ويب هوكَين بدلاً من واحد؟

Meta تتطلب GET للتحقق و POST للرسائل — لا يمكن دمجهما في نود واحد في n8n لأن كل منهما له منطق رد مختلف. الـ GET يرد بـ hub.challenge فقط، بينما الـ POST يبدأ مسار المعالجة الكامل.

هل HMAC إلزامي أم اختياري؟

تقنياً اختياري، لكن عملياً إلزامي في أي بوت يعمل في بيئة الإنتاج. بدونه أي شخص يعرف عنوان الـ Webhook الخاص بك يمكنه إرسال رسائل مزورة وتشغيل الـ workflow. مع البوتات التجارية هذا خطر لا يمكن تجاهله.

ما الفرق بين NoOp و Stop & Error لمعالجة الـ Status Webhooks؟

NoOp يُنهي الـ execution بهدوء دون تسجيل خطأ — مناسب للأحداث المتوقعة مثل Status webhooks. Stop & Error يسجّل الحادثة كخطأ في سجلات n8n مما يُربك المتابعة ويجعل من الصعب تمييز الأخطاء الحقيقية.

لماذا يتحقق Compare & Validate من الـ Timestamp؟

للحماية من هجمات إعادة التشغيل (Replay Attacks) — حيث يحاول المهاجم إعادة إرسال طلب قديم صحيح. التحقق من أن الرسالة ليست أقدم من 5 دقائق يمنع هذا النوع من الهجمات.

أين أجد الـ App Secret الخاص بتطبيقي في Meta؟

من لوحة Meta for Developers، اختر تطبيقك ← Settings ← Basic. ستجد الـ App Secret هناك. لا تشاركه مع أحد ولا تكتبه مباشرة في الـ workflow — خزّنه في n8n Credentials.

بناء بوت واتساب بـ n8n خطوة بخطوة — الويب هوك، الأمان، وتنظيم الرسائل (الحلقة الأولى)