ويب هوك العملاء المحتملين

انقل كل عميل محتمل جديد أو محدَّث من JackAI Nexus مباشرة إلى نظامك — Bitrix24 أو Zoho أو HubSpot أو Salesforce، أو أداة أتمتة مثل n8n وMake وZapier، أو خادمك الخاص.

بدل أن ينقل فريقك العملاء يدوياً، تسجّل رابطاً واحداً. ومن تلك اللحظة، كلما أُنشئ عميل أو تغيّرت بياناته في Nexus نرسله إليك تلقائياً — عادةً خلال دقيقة تقريباً.

---

البداية السريعة

١. احصل على رابط من نظامك

معظم الأدوات تعطيك رابط «ويب هوك» أو «طلب وارد»:

• Zoho Flow — أنشئ Flow، اختر Webhook كمُشغِّل، وانسخ الرابط الظاهر
• n8n — أضف عقدة Webhook وانسخ رابط الإنتاج منها
• Make / Zapier — أنشئ سيناريو أو Zap يبدأ بـ Webhook / Catch Hook
• خادمك الخاص — أي عنوان HTTPS يستقبل طلب POST بجسم JSON
• Bitrix24 — يتصل مباشرة دون أي أداة أتمتة. انظر Bitrix24 أدناه

٢. سجّله في Nexus

1. اذهب إلى الإعدادات ← الويب هوك
2. اضغط إضافة رابط
3. املأ الحقول:
   • الاسم — أي اسم يساعدك على تمييزه، مثل مزامنة Zoho
   • رابط الاستقبال — الرابط الذي نسخته في الخطوة الأولى
   • الأحداث — التغييرات التي تريد استقبالها (انظر الأحداث أدناه)
4. اضغط إنشاء

٣. أرسل تجربة

افتح الرابط الذي أنشأته واضغط إرسال تجريبي. سيرسل Nexus عميلاً نموذجياً فوراً ويعرض لك بالضبط ما ردّ به خادمك — رمز الحالة، ونص الرد، والزمن المستغرق.

إذا ظهرت النتيجة خضراء فقد انتهيت، وسيبدأ نظامك باستقبال العملاء الحقيقيين فور حدوثها.

---

Bitrix24

تستخدم Bitrix24؟ يكتب Nexus كل عميل مباشرة في نظام Bitrix24 لديك، دون الحاجة إلى Zapier أو Make أو n8n أو مبرمج.

١. أنشئ الرابط في Bitrix24

1. في Bitrix24 افتح Developer resources ← Other ← Inbound webhook
2. تحت Assign permissions أضف صلاحية CRM (crm)
3. اضغط Save، ثم انسخ رابط Webhook to call REST API، وشكله: https://yourcompany.bitrix24.com/rest/1/abc123xyz/

تعامل مع هذا الرابط ككلمة مرور. من يملكه يستطيع إضافة السجلات وتعديلها في نظامك، فلا تلصقه في المحادثات أو لقطات الشاشة. وإذا تسرّب، اضغط Generate new في Bitrix24.

٢. أضفه في Nexus

1. اذهب إلى الإعدادات ← الويب هوك واضغط إضافة رابط
2. من إرسال العملاء إلى اختر Bitrix24
3. الصق الرابط واضغط إنشاء

يُخفى الجزء السري من الرابط فور الحفظ.

٣. اختبر الاتصال

اضغط اختبار الاتصال. الاختبار يقرأ من Bitrix24 فقط ولا ينشئ أي عميل.

ما يصل إلى Bitrix24

• التعديلات تحدّث العميل نفسه. إذا تغيّر الرقم أو البريد يظهر الجديد في Bitrix24 مكان القديم، لا بجانبه.
• لا نحذف شيئاً من Bitrix24. وإذا حذف فريقك عميلاً من Bitrix24 فلن يعيده Nexus.
• العملاء الموجودون قبل الربط يصلون إلى Bitrix24 عند أول تغيير عليهم.
• إذا أنشأت رابطاً جديداً في Bitrix24 فافتح الرابط في Nexus واضغط تغيير الرابط. ما دام الحساب نفسه، يبقى العملاء المرسَلون سابقاً مرتبطين بسجلاتهم.

يستقبل Bitrix24 العملاء الجدد (lead.created) وتحديثاتهم (lead.updated). قسم التحقق من التوقيع أدناه لا ينطبق على Bitrix24، فالرابط السري نفسه هو ما يخوّل كل طلب.

---

الأحداث

اختر التغييرات التي تريد استقبالها. معظم التكاملات تشترك في lead.created وlead.updated.

عن lead.merged

يتعرّف Nexus على العميل نفسه عبر واتساب وماسنجر وإنستغرام والدردشة عبر رقم الهاتف. وحين يكتشف أن سجلَّين لشخص واحد يدمجهما ويرسل lead.merged. تحمل الرسالة المعرّف الذي اختفى وحقل merged_into بالمعرّف الباقي، لتدمج السجلَّين المقابلين لديك أيضاً.

---

ما الذي نرسله

كل طلب هو POST بجسم JSON بهذا الشكل:

{
  "type": "lead.updated",
  "timestamp": "2026-08-10T14:03:22+00:00",
  "data": {
    "id": "6a0e44b1-6d3c-4f9a-9b2e-2f1c8a7d4e10",
    "name": "أحمد السيد",
    "phone": "966501234567",
    "phone_e164": "+966501234567",
    "email": "ahmad@example.com",
    "country": "SA",
    "status": "interested",
    "score": 72,
    "summary": "يسأل عن شقق ثلاث غرف في مشروع الياسمين.",
    "interests": ["apartments", "yasmin-project"],
    "source": "conversation",
    "pipeline_excluded": false,
    "whatsapp_optout": false,
    "custom_fields": { "project_interest": "الياسمين" },
    "assigned_to": {
      "id": "7c1f...",
      "name": "سارة أحمد",
      "email": "sara@yourcompany.com"
    },
    "created_at": "2026-08-10T13:58:02+00:00",
    "updated_at": "2026-08-10T14:03:20+00:00",
    "changed_fields": ["status", "score"]
  }
}

الحقول

ملاحظة: الرسالة لقطة لحالة العميل لحظة الإرسال. وللحالة الأحدث دائماً، اعتبر لوحة تحكم Nexus المرجع.

---

قواعد الإرسال

قاعدتان تبني عليهما، وضبطهما يمنع تكرار السجلات واختلال ترتيبها في نظامك.

مرة واحدة على الأقل

نضمن وصول الويب هوك مرة واحدة على الأقل — وقد يصل الحدث نفسه مرتين أحياناً (مثلاً إذا استقبله خادمك لكن ردّه ضاع في الطريق).

ما العمل: كل طلب يحمل ترويسة webhook-id تبقى ثابتة عبر كل المحاولات. سجّل المعرّفات التي عالجتها وتجاهل المكرر.

الترتيب غير مضمون

قد يصل تغييران على العميل نفسه بترتيب معكوس.

ما العمل: قارن timestamp في الجسم واعتمد الأحدث. لا تفترض أن آخر طلب وصل هو آخر تغيير حصل.

التحديثات المجمّعة

أثناء محادثة العميل قد يحدّث الذكاء الاصطناعي بياناته عدة مرات خلال ثوانٍ. نجمع هذه التغييرات عمداً في lead.updated واحد بدل إرسال العشرات — حتى لا يُغرَق نظامك ولا تُستهلك حدود الطلبات لديك. ويسرد changed_fields كل ما تغيّر في المجموعة.

---

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

كل طلب موقَّع لتتأكد أنه من Nexus وليس من شخص خمّن رابطك.

نتبع مواصفة Standard Webhooks، ما يعني أنك تتحقق بمكتبة جاهزة بدل كتابة المنطق بنفسك.

الترويسات

webhook-id: evt_9f3a1c4b8d2e4f6a9c1b3d5e7f2a4c6b
webhook-timestamp: 1786370640
webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=

باستخدام مكتبة (الأفضل)

pip install standardwebhooks

from standardwebhooks import Webhook

# من الإعدادات ← الويب هوك — احفظه كسرّ ولا تضعه في الكود
secret = "whsec_..."

def handle_request(headers, raw_body: bytes):
    wh = Webhook(secret)
    payload = wh.verify(raw_body, headers)   # يرفع خطأ إذا كان التوقيع غير صالح
    lead = payload["data"]
    print(lead["id"], lead["status"], lead["score"])
    return "", 200

وبنفس الطريقة في JavaScript:

npm install standardwebhooks

import { Webhook } from "standardwebhooks";

const wh = new Webhook(process.env.NEXUS_WEBHOOK_SECRET);
const payload = wh.verify(rawBody, headers);   // يرمي خطأ إذا كان غير صالح

التحقق يدوياً

إن فضّلت عدم إضافة مكتبة، فالتوقيع هو HMAC-SHA256 للمعرّف والوقت والجسم الخام موصولة بنقاط:

import base64, hashlib, hmac

def is_valid(secret: str, headers, raw_body: bytes) -> bool:
    msg_id = headers["webhook-id"]
    timestamp = headers["webhook-timestamp"]
    signed_content = f"{msg_id}.{timestamp}.{raw_body.decode()}".encode()

    key = base64.b64decode(secret.removeprefix("whsec_"))
    expected = base64.b64encode(
        hmac.new(key, signed_content, hashlib.sha256).digest()
    ).decode()

    # قد تحمل الترويسة عدة توقيعات مفصولة بمسافة أثناء تدوير المفتاح
    for entry in headers["webhook-signature"].split(" "):
        version, _, signature = entry.partition(",")
        if version == "v1" and hmac.compare_digest(signature, expected):
            return True
    return False

نقطتان يجب ضبطهما:

• وقّع جسم الطلب الخام كما وصل تماماً. فإذا حلّل إطار العمل الـ JSON ثم أعدت تحويله إلى نص، تتغير البايتات ولن يتطابق التوقيع أبداً.
• استخدم مقارنة ثابتة الزمن (hmac.compare_digest) لا ==.

رفض الطلبات المُعادة

تحقق أيضاً أن webhook-timestamp ضمن دقائق قليلة من وقتك الحالي — ننصح بـ ٥ دقائق. هذا يمنع من يلتقط طلباً صالحاً من إعادة إرساله لاحقاً.

---

تدوير المفتاح

إذا انكشف مفتاحك يوماً، افتح الرابط واضغط تدوير المفتاح.

يظل المفتاح القديم صالحاً ٢٤ ساعة ليتسع لك الوقت لنشر الجديد دون فقدان أي عميل. وخلال هذه المدة نوقّع كل طلب بالمفتاحين، فتحمل ترويسة webhook-signature توقيعين مفصولين بمسافة — ومكتبات التحقق تعالج ذلك تلقائياً.

---

الرد الصحيح

ردّ برمز 2xx فور حفظك للحدث بأمان، وأجّل العمل البطيء — الكتابة في نظامك، إرسال الإيميلات — إلى بعد الرد.

@app.post("/nexus-webhook")
def nexus_webhook():
    payload = verify_and_parse(request)
    queue.enqueue(process_lead, payload)   # نفّذ العمل الفعلي في الخلفية
    return "", 200                          # وردّ فوراً

تنتهي مهلة الطلب بعد ١٠ ثوانٍ، والرابط البطيء يبدو كأنه فاشل فتُعاد المحاولة دون داعٍ.

ماذا يعني كل رد

---

حين يحدث خلل

آخر عمليات الإرسال

افتح الرابط واضغط عرض آخر عمليات الإرسال. كل محاولة مسجّلة برمز الحالة ونص الرد الذي استقبلناه والزمن المستغرق — وغالباً يكفي ذلك لمعرفة المشكلة دون فتح سجلاتك.

إعادة المحاولة التلقائية

تُعاد المحاولة الفاشلة بفواصل متزايدة (ثوانٍ ثم دقائق ثم ساعات) حتى ٢٤ ساعة، فانقطاع قصير عندك لا يفقدك شيئاً.

التعطيل التلقائي

إذا استمر الفشل مدة أطول نعطّل الرابط ونرسل بريداً لمدراء مؤسستك. لا شيء يُهمَل بصمت — ستعرف دائماً.

ولإعادة تشغيله: أصلح الرابط ثم افتح الإعدادات ← الويب هوك وفعّله من جديد، ليُصفَّر عدّاد الأخطاء.

أسباب شائعة

---

ملاحظات أمنية

• تعامل مع مفتاح التوقيع كأنه كلمة مرور. احفظه في متغيرات البيئة أو مدير الأسرار، لا في الكود.
• HTTPS فقط. لا نرسل إلى عناوين http:// العادية.
• عناوين عامة فقط. الروابط على الشبكات الداخلية أو الخاصة مرفوضة في الاتجاهين.
• تحقق من التوقيع. رابطك ليس سرّاً، وأي شخص يعرفه يستطيع الإرسال إليه. التوقيع وحده هو ما يثبت أن الطلب منّا فعلاً.

---

أسئلة شائعة

هل أحتاج مبرمجاً؟ ليس للأساسيات. Zoho Flow وn8n وMake وZapier تستقبل الويب هوك وتربط الحقول بلا كود. المبرمج مطلوب فقط للتحقق من التوقيع، وهو اختياري مع هذه الأدوات لأن رابطك خاص أصلاً.

هل يؤثر هذا على عملائي أو على ردود الذكاء الاصطناعي؟ لا. الويب هوك يقرأ ما حدث فعلاً فقط، وتسجيله لا يغيّر شيئاً في طريقة حديث الذكاء الاصطناعي مع العملاء.

هل سيرسل عملائي الحاليين؟ لا. فقط التغييرات من لحظة إنشاء الرابط. استخدم العملاء ← تصدير للحصول على نسخة لمرة واحدة مما لديك.

هل تدعمون Bitrix24؟ نعم، مباشرة. اختر Bitrix24 عند إضافة الرابط والصق رابط الويب هوك الوارد من Bitrix24. انظر Bitrix24.

هل أرسل إلى أكثر من نظام؟ نعم. أضف رابطاً لكل نظام. تُرسَل بشكل مستقل، فتعطّل أحدها لا يؤثر على البقية.

ما سرعة الوصول؟ عادةً خلال دقيقة تقريباً من التغيير. والتحديثات أثناء محادثة نشطة تُجمَّع، فتصل متأخرة قليلاً لكن كتحديث واحد مكتمل.