دليل المطور المتقدم لـ واتساب API: Webhooks وأحداث وأمان

دليل المطور المتقدم لـ واتساب API: Webhooks وأحداث وأمان

إذا أنت مطور وتبي تبني تكامل متقدم مع واتساب API، هالدليل لك. بنغطي الجوانب التقنية المتقدمة، من إعداد Webhooks للتحقق من صحة الرسائل بـ HMAC لأفضل ممارسات الأمان.

إعداد Webhook متين

الـ Webhook هو الأساس، كل حدث في واتساب (رسالة جديدة، قراءة، توصيل، فشل) يوصلك عبره.

المتطلبات التقنية:

• سيرفر HTTPS بشهادة SSL صالحة (Let's Encrypt كافي)
• الاستجابة خلال 5 ثواني، أي تأخير يعتبر فشل
• معالجة POST requests بـ JSON body
• تأكيد Verification Challenge (GET request) عند التسجيل

بنية Endpoint الموصى بها:

POST /webhook/whatsapp
Headers: Content-Type: application/json
Body: { "object": "whatsapp_business_account", "entry": [...] }

نصائح مهمة:

• رد 200 OK فوراً: استلم الحدث، رد 200، وعالجه في الخلفية (queue). لا تعالج في نفس الطلب
• Idempotency: واتساب يعيد الإرسال لو ما استلم 200. لازم تتعامل مع الأحداث المكررة بـ message ID
• Retry Logic: واتساب يعيد المحاولة حتى 7 مرات على مدى 72 ساعة

التحقق بـ HMAC

كل طلب Webhook من واتساب يجي مع توقيع HMAC في الهيدر X-Hub-Signature-256. لازم تتحقق:

signature = HMAC-SHA256(app_secret, request_body)
compare(signature, header['X-Hub-Signature-256'])

ليش مهم: بدون التحقق، أي شخص يقدر يرسل طلبات مزيفة لـ endpoint حقك ويتلاعب بالبيانات.

أنواع الأحداث

واتساب API يرسل عدة أنواع من الأحداث:

الحدث	الوصف	الاستخدام
messages	رسالة جديدة	الرد على العميل
statuses	تحديث حالة الرسالة	sent, delivered, read, failed
message_template_quality_update	تغيير جودة القالب	مراقبة صحة القوالب
account_update	تحديث حساب	تغيير في حالة الحساب
message_template_status_update	تحديث حالة القالب	موافقة أو رفض

معالجة الأحداث

بنية الحدث:

{
  "object": "whatsapp_business_account",
  "entry": [{
    "id": "WABA_ID",
    "changes": [{
      "value": {
        "messaging_product": "whatsapp",
        "metadata": { "phone_number_id": "...", "display_phone_number": "..." },
        "messages": [{ "id": "wamid.xxx", "from": "966...", "type": "text", "text": { "body": "..." } }]
      },
      "field": "messages"
    }]
  }]
}

نصائح المعالجة:

• خزّن wamid لكل رسالة، هو المعرّف الفريد
• تعامل مع كل نوع رسالة (text, image, document, location, contacts, interactive, button)
• سجّل كل حدث في log للمراجعة

Rate Limiting والحدود

واتساب API عنده حدود لازم تحترمها:

• رسائل لكل ثانية: حسب مستوى حسابك (80-250 msg/sec)
• طلبات API: 200 طلب/ساعة لكل رقم هاتف
• رفع ملفات: حد أقصى 100 MB لكل ملف
• حجم الرسالة: حد أقصى 4,096 حرف للرسائل النصية

التعامل مع Rate Limit:

• طبّق Exponential Backoff
• استخدم Message Queue (Redis/RabbitMQ) لإدارة الإرسال
• راقب الحدود من الـ response headers

أفضل ممارسات الأمان

1. لا تخزّن Access Token في الكود: استخدم Environment Variables أو Secret Manager
2. فعّل IP Whitelisting: اسمح بس لعناوين IP المعروفة
3. شفّر البيانات في الراحة: البيانات المخزنة (رسائل، أرقام) لازم تكون مشفرة
4. دوّر التوكنات: غيّر Access Token كل 60-90 يوم
5. سجّل كل شي: Audit Log لكل عملية API
6. أقل صلاحية ممكنة: كل تطبيق أو مستخدم يأخذ بس الصلاحيات اللي يحتاجها

اختبار التكامل

• Sandbox: استخدم رقم Sandbox للاختبار قبل الإنتاج
• Webhook Testing: أدوات مثل ngrok لاختبار Webhooks محلياً
• Mock Server: ابنِ Mock Server يحاكي ردود واتساب للاختبارات الآلية
• Error Scenarios: اختبر سيناريوهات الفشل، timeout، rate limit، invalid token

واتس لووب API: البديل الأسهل

لو تبي تختصر الوقت، واتس لووب يعطيك API جاهز:

• 3 أسطر كود ترسل فيها أول رسالة
• Webhooks مبسّطة: أحداث واضحة ومنظمة بدون تعقيد Meta
• SDK متوفر لـ Node.js وPHP وPython
• توثيق كامل مع أمثلة عملية

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

س: هل أحتاج خبرة متقدمة في البرمجة عشان أربط مع واتساب API؟ ج: واتس لووب يوفر API مبسّط مع SDK جاهز لـ Node.js وPHP وPython. تقدر ترسل أول رسالة بـ 3 أسطر كود فقط، والتوثيق يشرح كل خطوة بأمثلة عملية.

س: كيف أتعامل مع الأحداث المكررة من Webhook واتساب؟ ج: استخدم معرّف الرسالة الفريد (wamid) لتطبيق Idempotency. خزّن كل wamid استلمته، ولو جاك نفس المعرّف مرة ثانية تجاهله. واتساب يعيد الإرسال حتى 7 مرات لو ما استلم رد 200 OK.

س: إيش الفرق بين واتساب Cloud API وواتس لووب API؟ ج: Cloud API من ميتا يحتاج إعداد Webhooks وتحقق HMAC وتعامل مع بنية أحداث معقدة. واتس لووب API يبسّط كل هالشي، أحداث واضحة ومنظمة، بدون تعقيد، مع دعم فني.

س: هل واتس لووب يوفر بيئة اختبار (Sandbox) مجانية للمطورين؟ ج: نعم، تقدر تبدأ بـ حساب مجاني واختبار الـ API والـ Webhooks بدون تكلفة. البيئة تشمل توثيق كامل وأمثلة جاهزة لكل لغة برمجة مدعومة.

ابدأ الحين

واتس لووب يعطيك API قوي مع توثيق واضح وأمثلة جاهزة. ابنِ تكاملك في ساعات بدل أسابيع. جرب الـ Sandbox مجاناً.