الإجابة المختصرة
لتستقبل رسائل عملائك على واتساب في نظامك سجّل رابط HTTPS عام على سيرفرك بطلب POST إلى https://sog.sog.eg/api/whatsapp/webhooks، واحفظ الـ secret الذي يرجع. بعدها يرسل لك كل رد من عميل كحدث message.inbound وكل رسالة خرجت كحدث message.sent، موقّعًا بالهيدر X-SOG-Signature. تحقّق من التوقيع بـ HMAC-SHA256 ورد بـ 200 خلال 8 ثوانٍ.
في هذه الصفحة
خطوات ربط الـ Webhook
الخطوة 1: جهّز رابطًا على سيرفرك
رابط عام يستقبل طلبات
POSTبصيغة JSON، مثلhttps://example.com/hooks/whatsapp. لا يُقبلlocalhostأو عنوان شبكة داخلية. الميزة تحتاج الويب هوك في باقتك.الخطوة 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: تحقّق من التوقيع في كل طلب
احسب 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: رد بسرعة ثم عالج الحدث
رد بـ
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 ينقل نص الرسالة فقط. الصور والملفات الواردة تظهر في واتساب على الموبايل المربوط.payload وsender وreceiver بدون توقيع. التفاصيل في قسم المنصة القديمة.جاهز تبدأ؟
كيف تستقبل ردود عملائك على واتساب في نظامك عبر Webhook

