Webhook وارد

ابعت رسايل وعملاء من فورمات موقعك أو بوابة واتساب خاصة لـ PropDrop بطلب POST موقّع، والوكيل الذكي يرد عليهم.

الـ Webhook الوارد هو الباب العكسي: أي سيستم عندك يقدر يبعت لـ PropDrop رسالة عميل أو عميل جديد. مثلًا:

فورم «اطلب تفاصيل» على موقعك.
بوابة واتساب أو SMS خاصة (غير Meta).
أداة زي n8n بتجمع عملاء من الإعلانات أو من ملفات البوابات العقارية.

الرسالة بتدخل صندوق المحادثات زي أي قناة، والعميل بيتسجل في العملاء، والوكيل الذكي بيرد. ورد الوكيل بيطلع على الـ Webhook الصادر، فبوابتك هي اللي توصّله للعميل.

PropDrop مش بيسحب من البوابات العقارية

PropDrop مش بيتربط مباشرة بـ Property Finder أو Bayut أو عقار ماب. لو عندك عملاء من هناك، لازم سيستم عندك (زي n8n) يبعتهم للرابط ده بالشكل اللي تحت.

الصفحة دي للشخص التقني. متاح في كل الباقات. مين يقدر يظبطه: المالك والمدير.

التجهيز

انسخ «رابط الاستقبال»

من «الإعدادات ← القنوات والربط»، تحت «متقدم»، افتح «استقبال رسائل وعملاء من برّه (inbound webhook)» وانسخ الرابط. شكله كده:

https://…/api/webhooks/inbound/<رقم شركتك>

اعمل «مفتاح التوقيع السري»

دوس «اعمل مفتاح جديد» وانسخ المفتاح (بيبدأ بـ pd_in_). بيظهر مرة واحدة بس. ده مفتاح مختلف عن مفتاح الـ Webhook الصادر. لو عملت مفتاح جديد، القديم بيبطل فورًا.

خلّي بوابتك توقّع كل طلب

كل طلب لازم يكون فيه:

X-PropDrop-Signature: sha256=<hex HMAC-SHA256(secret, raw body)>

يعني HMAC-SHA256 بالمفتاح على جسم الطلب زي ما هو بالظبط. أي طلب من غير توقيع صحيح بيترفض.

شكل الطلب

POST https://…/api/webhooks/inbound/<رقم شركتك>
Content-Type: application/json
X-PropDrop-Signature: sha256=…

{
  "channel": "whatsapp",
  "source": "portal",
  "external_id": "lead-48213",
  "sent_at": "2026-10-09T12:00:00+02:00",
  "text": "مهتم بالشقة اللي في التجمع، ممكن السعر؟",
  "contact": { "name": "Ahmed Ali", "phone": "+201001234567" }
}

الحقل	مطلوب؟	التفاصيل
`contact.phone` أو `contact.instagram`	واحد منهم لازم	الرقم بيتظبط لوحده حسب دولة شركتك (مثلًا `01001234567` بيبقى `+201001234567`)
`contact.name`	لأ	لحد 120 حرف
`contact.email`	لأ	إيميل صحيح
`text`	لازم (أو `attachments`)	لحد 4000 حرف
`channel`	لأ	`whatsapp` (الافتراضي)، `sms`، `email`، `web`، `instagram`، `messenger`، `telegram`
`source`	لأ	مصدر العميل الجديد. `portal` بيسجله إنه «بوابة عقارية». وفيه كمان `web`، `phone`، `referral`، `manual`، `import` وأسامي القنوات
`external_id`	لأ (بس مهم)	رقمك إنت للرسالة، لحد 200 حرف. أي طلب بنفس الرقم بيتجاهل، فإعادة الإرسال آمنة
`sent_at`	لأ	وقت الرسالة بصيغة ISO 8601 بالـ timezone
`attachments`	لأ	لحد 10 مرفقات (تحت)

المرفقات

"attachments": [
  { "type": "image", "url": "https://example.com/plan.jpg", "mime": "image/jpeg", "name": "plan.jpg" },
  { "type": "location", "lat": 30.0131, "lng": 31.4914, "label": "التجمع الخامس" }
]

type: image أو audio أو video أو document أو location. الروابط لازم تبدأ بـ https://، وإحنا بننسخ الملف ونحفظه في المحادثة.

الردود

الكود	المعنى
`202`	اتسجل: `{"ok": true, "event_id": "…"}`. الرسالة بتتعالج بعدها والوكيل بيرد
`400`	`invalid_json`، أو `invalid` ومعاه `issues` بتقولك أنهي حقل غلط
`401`	`invalid_signature`: التوقيع ناقص أو غلط
`403`	`agency_inactive`: حساب الشركة متوقف
`404`	`not_found`: الرابط غلط
`413`	`too_large`: الجسم أكبر من 256 KB

لو الطلب اتقبل (202) وحصلت مشكلة وإحنا بنعالجه، بنعيد معالجته تلقائيًا بعد شوية.

العميل بيتسجل إزاي؟

بندوّر على العميل بالرقم (أو حساب إنستجرام). لو موجود، الرسالة بتتضاف عنده. لو مش موجود، بيتعمل عميل جديد بالمصدر اللي في source.
لو العميل عنده محادثة مفتوحة على نفس القناة، الرسالة بتدخل فيها.

لو ربطت واتساب من PropDrop كمان

لو العميل نفسه عنده محادثة واتساب مفتوحة على رقمك المربوط في PropDrop، والطلب جاي بـ "channel": "whatsapp"، الرسالة هتدخل المحادثة دي والرد هيطلع من رقمك المربوط مش من بوابتك. لو بوابتك رقم تاني، استخدم "channel": "sms" أو قناة مختلفة عشان المحادثات متتخلطش.

جرّب بسرعة

BODY='{"text":"عايز شقة في التجمع","contact":{"name":"Test","phone":"+201001234567"},"external_id":"test-1"}'
SIG="sha256=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$SECRET" -hex | sed 's/^.* //')"
curl -X POST "$INBOUND_URL" -H "Content-Type: application/json" -H "X-PropDrop-Signature: $SIG" -d "$BODY"

لو رجعلك 202، افتح المحادثات: هتلاقي المحادثة ورد الوكيل، والرد هيروح لـالـ Webhook الصادر لو متظبط.

Webhook وارد

التجهيزانسخ لينك القسم

انسخ «رابط الاستقبال»انسخ لينك القسم

اعمل «مفتاح التوقيع السري»انسخ لينك القسم

خلّي بوابتك توقّع كل طلبانسخ لينك القسم

شكل الطلبانسخ لينك القسم

المرفقاتانسخ لينك القسم

الردودانسخ لينك القسم

العميل بيتسجل إزاي؟انسخ لينك القسم

جرّب بسرعةانسخ لينك القسم

في الصفحة دي