نظرة عامة
Webhooks هي طريقة للحصول على إشعارات فورية عندما تحدث أحداث مهمة في منصتك. بدلاً من الاستعلام المتكرر (polling)، تُرسل المنصة طلب HTTP POST تلقائياً لعنوان URL الذي تحدده أنت.
🔒 الأمان أولاً: كل طلب يحمل توقيعاً رقمياً بـ HMAC-SHA256 يمكّنك من التحقق أن الطلب قادم فعلاً من شوف عقار.
1حدث يقع
قبول عرض سعر
قبول عرض سعر
←
2HTTP POST
لعنوانك
لعنوانك
←
3أتمتتك
CRM / واتساب
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-type | application/json | دائماً JSON |
x-shoufaqar-signature | sha256=abc... | توقيع HMAC-SHA256 |
x-shoufaqar-event | quotation.accepted | نوع الحدث للفلترة |
x-shoufaqar-delivery-id | uuid-v4 | معرّف فريد لمنع التكرار |
x-shoufaqar-timestamp | 1787449633 | Unix timestamp |
user-agent | Shoufaqar-Webhooks/1.0 | هوية المُرسِل |
إعادة المحاولة
إذا لم يستجب عنوانك بـ 2xx خلال 10 ثوانٍ، ستُعاد المحاولة:
1بعد 5 دقائق
2بعد 30 دقيقة
3بعد 2 ساعة
⚠️ تنبيه: استخدم
x-shoufaqar-delivery-id لمنع معالجة نفس الحدث مرتين (Idempotency). الربط مع Zapier
- أنشئ Zap جديد — اختر "Webhooks by Zapier" كـ Trigger
- اختر "Catch Hook" — انسخ الـ URL المُوَلَّد
- في لوحة شوف عقار → الأتمتة → أضف نقطة ربط → الصق الـ URL واختر الأحداث
- اضغط "Test" في لوحة التحكم — Zapier سيستقبل البيانات فوراً
- أكمل الـ Zap — أضف Action (واتساب، Google Sheets، CRM...)
💡 أفكار شائعة:
- quotation.accepted → صفقة جديدة في HubSpot / Salesforce
- tour.lead_captured → واتساب فوري للوكيل عبر WhatsApp Cloud API
- quotation.viewed → إشعار Slack للفريق
- quotation.expired → بريد تذكيري للوكيل للمتابعة
الربط مع n8n
- أضف Node من نوع "Webhook" — Method: POST
- انسخ الـ Production URL والصقه في لوحة التحكم
- أضف 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
←
بريد تذكير 📧