⚡ توثيق المطورين

Webhooks API

ربط منصة شوف عقار بأي نظام خارجي — Zapier أو n8n أو كودك الخاص. كل حدث يُطلق إشعاراً فورياً آمناً لعنوانك المحدد.

متاح في باقة أعمال وبريميومHMAC-SHA256JSON / HTTP POST

نظرة عامة

Webhooks هي طريقة للحصول على إشعارات فورية عندما تحدث أحداث مهمة في منصتك. بدلاً من الاستعلام المتكرر (polling)، تُرسل المنصة طلب HTTP POST تلقائياً لعنوان URL الذي تحدده أنت.

🔒 الأمان أولاً: كل طلب يحمل توقيعاً رقمياً بـ HMAC-SHA256 يمكّنك من التحقق أن الطلب قادم فعلاً من شوف عقار.
1حدث يقع
قبول عرض سعر
←
2HTTP POST
لعنوانك
←
3أتمتتك
CRM / واتساب

الأحداث المتاحة

📄
quotation.created

إنشاء عرض سعر جديد

📤
quotation.sent

إرسال عرض السعر للعميل

👁️
quotation.viewed

فتح العميل رابط العرض (أول مرة)

✅
quotation.accepted

العميل قبل عرض السعر

❌
quotation.rejected

العميل رفض عرض السعر

⏰
quotation.expired

انتهت صلاحية عرض السعر

🎯
tour.lead_captured

عميل أبدى اهتماماً بجولة افتراضية

🎥
co_browsing.started

بدأت جلسة جولة حية مشتركة

💡 نصيحة: يمكنك تحديد الأحداث التي تستقبلها كل نقطة ربط — لا تجبر على استقبال الجميع.

بنية الـ Payload

جميع الأحداث تتبع نفس الهيكل:

quotation.accepted — مثالapplication/json
{
  "event":       "quotation.accepted",
  "event_id":    "evt_01J5X2...",
  "delivery_id": "d63dc535-ed36-4108-965a-f498fbaf7931",
  "timestamp":   1787449633,
  "api_version": "1.0",
  "data": {
    "quotation_id":   "qtn_...",
    "client_name":    "محمد العمري",
    "property_title": "فيلا — حي الملقا، الرياض",
    "total_amount":   1250000,
    "currency":       "SAR",
    "responded_at":   "2026-08-23T17:44:33Z"
  }
}
tour.lead_captured — مثال
{
  "event":     "tour.lead_captured",
  "timestamp": 1787449633,
  "data": {
    "tour_id":        "tour_...",
    "tour_title":     "جولة فيلا الملقا",
    "client_name":    "سارة الغامدي",
    "client_phone":   "0501234567",
    "request_type":   "live_tour",
    "preferred_time": "بعد الساعة 5 مساءً",
    "captured_at":    "2026-08-23T17:44:33Z"
  }
}

التحقق من التوقيع

كل طلب يحمل رأس x-shoufaqar-signature بتوقيع HMAC-SHA256. يجب التحقق منه دائماً.

Node.js / Express
const crypto = require('crypto')

function verifySignature(rawBody, signature, secret) {
  const expected = 'sha256=' +
    crypto.createHmac('sha256', secret)
          .update(rawBody).digest('hex')
  return crypto.timingSafeEqual(
    Buffer.from(expected), Buffer.from(signature)
  )
}

app.post('/webhook', (req, res) => {
  const sig = req.headers['x-shoufaqar-signature']
  if (!verifySignature(JSON.stringify(req.body), sig, process.env.SECRET))
    return res.status(401).send('Invalid signature')

  const { event, data } = req.body
  console.log('Event:', event, data)
  res.sendStatus(200)
})

الـ Headers

الرأسالمثالالوصف
content-typeapplication/jsonدائماً JSON
x-shoufaqar-signaturesha256=abc...توقيع HMAC-SHA256
x-shoufaqar-eventquotation.acceptedنوع الحدث للفلترة
x-shoufaqar-delivery-iduuid-v4معرّف فريد لمنع التكرار
x-shoufaqar-timestamp1787449633Unix timestamp
user-agentShoufaqar-Webhooks/1.0هوية المُرسِل

إعادة المحاولة

إذا لم يستجب عنوانك بـ 2xx خلال 10 ثوانٍ، ستُعاد المحاولة:

1بعد 5 دقائق
2بعد 30 دقيقة
3بعد 2 ساعة
⚠️ تنبيه: استخدم x-shoufaqar-delivery-id لمنع معالجة نفس الحدث مرتين (Idempotency).

الربط مع Zapier

  1. أنشئ Zap جديد — اختر "Webhooks by Zapier" كـ Trigger
  2. اختر "Catch Hook" — انسخ الـ URL المُوَلَّد
  3. في لوحة شوف عقار → الأتمتة → أضف نقطة ربط → الصق الـ URL واختر الأحداث
  4. اضغط "Test" في لوحة التحكم — Zapier سيستقبل البيانات فوراً
  5. أكمل الـ Zap — أضف Action (واتساب، Google Sheets، CRM...)
💡 أفكار شائعة:
  • quotation.accepted → صفقة جديدة في HubSpot / Salesforce
  • tour.lead_captured → واتساب فوري للوكيل عبر WhatsApp Cloud API
  • quotation.viewed → إشعار Slack للفريق
  • quotation.expired → بريد تذكيري للوكيل للمتابعة

الربط مع n8n

  1. أضف Node من نوع "Webhook" — Method: POST
  2. انسخ الـ Production URL والصقه في لوحة التحكم
  3. أضف Code Node للتحقق من التوقيع:
n8n — Code Node
const crypto = require('crypto')
const secret = $env.SHOUFAQAR_SECRET
const sig    = $input.first().headers['x-shoufaqar-signature']
const body   = JSON.stringify($input.first().body)
const expected = 'sha256=' +
  crypto.createHmac('sha256', secret).update(body).digest('hex')
if (sig !== expected) throw new Error('Invalid signature')
return $input.all()

أمثلة عملية

🎯 إشعار واتساب عند التقاط عميل جديد

tour.lead_captured
←
Zapier / n8n
←
WhatsApp API → وكيل 📱

✅ تحديث CRM عند قبول عرض السعر

quotation.accepted
←
Zapier
←
HubSpot Deal 🏆

⏰ متابعة عروض منتهية الصلاحية

quotation.expired
←
n8n
←
بريد تذكير 📧