الموقع فى النسخه التجربيه الان
واتساب API والربط البرمجي

كيف تستقبل ردود عملائك على واتساب في نظامك عبر Webhook

فريق دعم سمارت ون جروبآخر تحديث: 5 دقائق قراءة

الإجابة المختصرة

لتستقبل رسائل عملائك على واتساب في نظامك سجّل رابط HTTPS عام على سيرفرك بطلب POST إلى https://sog.sog.eg/api/whatsapp/webhooks، واحفظ الـ secret الذي يرجع. بعدها يرسل لك كل رد من عميل كحدث message.inbound وكل رسالة خرجت كحدث message.sent، موقّعًا بالهيدر X-SOG-Signature. تحقّق من التوقيع بـ HMAC-SHA256 ورد بـ 200 خلال 8 ثوانٍ.

في هذه الصفحة

خطوات ربط الـ Webhook

  1. الخطوة 1: جهّز رابطًا على سيرفرك

    رابط عام يستقبل طلبات POST بصيغة JSON، مثل https://example.com/hooks/whatsapp. لا يُقبل localhost أو عنوان شبكة داخلية. الميزة تحتاج الويب هوك في باقتك.

  2. الخطوة 2: سجّل الرابط واحفظ الـ secret

    أرسل POST /webhooks بالحقل url ومفاتيحك. الرد يحمل secret من 40 حرفًا؛ احفظه في إعدادات سيرفرك. كل تسجيل جديد يستبدل الرابط ويُصدر secret جديدًا.

    curl -X POST https://sog.sog.eg/api/whatsapp/webhooks \
      -H "Accept: application/json" \
      -d appkey=YOUR_API_KEY -d authkey=YOUR_SECRET_KEY \
      -d url=https://example.com/hooks/whatsapp
    
    # → 200 {"data":{"url":"https://example.com/hooks/whatsapp",
    #        "secret":"Q2x8…40 characters…"}}
    # Store the secret on your server. Calling this again issues a new one.
  3. الخطوة 3: تحقّق من التوقيع في كل طلب

    احسب HMAC-SHA256 لجسم الطلب كما وصل (قبل تحويله من JSON) بالـ secret، وقارنه بالهيدر X-SOG-Signature. ارفض أي طلب لا يطابق.

    <?php
    $raw = file_get_contents('php://input');
    $expected = hash_hmac('sha256', $raw, getenv('SOG_WA_WEBHOOK_SECRET'));
    $given = $_SERVER['HTTP_X_SOG_SIGNATURE'] ?? '';
    
    if (! hash_equals($expected, $given)) {
        http_response_code(401);
        exit;
    }
    
    $event = json_decode($raw, true);
    // Queue $event for processing, then answer quickly.
    http_response_code(200);
  4. الخطوة 4: رد بسرعة ثم عالج الحدث

    رد بـ 200 خلال 8 ثوانٍ، وعالج الحدث بعدها في الخلفية (طابور مهام مثلًا). كل حدث يُرسل مرة واحدة فقط.

ما الأحداث التي تصل إلى الـ Webhook؟

اسم الحدث يصل في جسم الطلب في event وفي الهيدر X-SOG-Event:

الحدثمتى يصلالحقول في `data`
message.inboundعندما يرسل عميل رسالة نصية إلى رقمك المربوط.phone وtext وhanded_off (هل حوّلتها قاعدة شات بوت لموظف)
message.sentعندما تخرج رسالة من رقمك: من الـ API أو حملة أو جدولة أو رد تلقائي.id وto وtype وmessage_id
POST /hooks/whatsapp
Content-Type: application/json
X-SOG-Event: message.inbound
X-SOG-Signature: 5f2c…(HMAC-SHA256 hex)

{
  "event": "message.inbound",
  "data": {
    "phone": "201012345678",
    "text": "Is my order ready?",
    "handed_off": false
  }
}

ماذا لو كان سيرفري متوقفًا وفاتني حدث؟

المنصة تحاول توصيل كل حدث مرة واحدة ولا تعيد المحاولة. لتعويض ما فاتك اقرأ آخر 100 رسالة واردة من GET /inbox، وحالة أي رسالة أرسلتها من GET /messages/{id} كما في مرجع WhatsApp API.

كيف أؤمّن رابط الـ Webhook؟

  • استخدم HTTPS دائمًا، واجعل الرابط صعب التخمين.
  • تحقق من X-SOG-Signature في كل طلب باستخدام مقارنة آمنة زمنيًا مثل hash_equals أو timingSafeEqual.
  • لا تكتب الـ secret في الكود؛ ضعه في متغيرات البيئة، وإذا تسرب سجّل الرابط من جديد للحصول على secret جديد.

أسئلة متكررة

حدث message.inbound ينقل نص الرسالة فقط. الصور والملفات الواردة تظهر في واتساب على الموبايل المربوط.

لا. في المنصة القديمة تضبط رابط الـ Webhook في إعدادات الجهاز، ويصلك الطلب بالحقول payload وsender وreceiver بدون توقيع. التفاصيل في قسم المنصة القديمة.

سجّل رابطًا جديدًا يرد بـ 200 دون معالجة، أو افتح تذكرة دعم لإيقاف الرابط من حسابك.

جاهز تبدأ؟

كيف تستقبل ردود عملائك على واتساب في نظامك عبر Webhook

افتح مفاتيح الـ API