الإشعارات الصادرة

يرسل الإشعار الصادر (Webhook) رسالة موقّعة إلى عنوان تملكه كلما حدث شيء مهم في رُتبة CRM. استخدمه لبدء عمل في نظام آخر: تنبيه قناة، أو إضافة صف إلى جدول عبر أداة أتمتة، أو تحديث برمجيتك الخاصة.

قبل أن تبدأ

• من يستطيع ذلك: مالك الشركة ومسؤولوها.
• الباقة: متاح عندما تشمل باقتك واجهة API.
• عنوان HTTPS يقبل طلبات POST على المنفذ المعتاد 443. أدوات الأتمتة مثل Zapier وMake وn8n تعطيك عنوانًا عند إنشاء مشغّل Webhook.

أضف عنوانًا

1. من القائمة الجانبية افتح جهات الاتصال، ثم اضغط مفاتيح API، ثم الإشعارات الصادرة.
2. في إضافة عنوان اكتب عنوان HTTPS.
3. في أرسل عند اختر حدثًا أو أكثر:

4. اضغط إضافة عنوان.
5. يظهر مربع فيه سر التوقيع، ويبدأ بـwhsec_. انسخه الآن، فلن يظهر مرة أخرى.

للشركة حتى 5 عناوين، بما فيها الموقوفة والمنشأة عبر API، وتظهر كلها في الصفحة نفسها. أما العناوين المزالة فلا تُحسب. ولا يمكن تغيير العنوان أو أحداثه بعد إضافته: لتغييرها أضف عنوانًا جديدًا وأزل القديم.

إيقاف عنوان أو إزالته

لكل عنوان في صفحة الإشعارات الصادرة زرّان:

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

وتبقى إرسالاته السابقة في آخر الأحداث حتى يمر عليها 30 يومًا.

ما يُرسل

كل إرسال طلب POST بجسم JSON:

{
  "id": "DELIVERY_ID",
  "event": "order_confirmed",
  "occurred_at": "2026-11-08T09:30:00Z",
  "data": {
    "contact": {"id": "CONTACT_ID", "name": "Sample Customer", "email": "customer@example.com", "phone": "+966500000001"},
    "subject": "order:ORDER_ID",
    "amount_minor": 125050,
    "currency": "SAR"
  }
}

ومعه ثلاث ترويسات:

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

SIGNATURE هو HMAC-SHA256 بصيغة hex للنص TIMESTAMP.BODY، بمفتاح هو سر التوقيع، وBODY هو الجسم الخام كما وصل. تحقق منه قبل أن تثق بأي إرسال:

$body = file_get_contents('php://input');
preg_match('/t=(\d+),v1=([a-f0-9]+)/', $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '', $parts);
$expected = hash_hmac('sha256', ($parts[1] ?? '').'.'.$body, getenv('WEBHOOK_SECRET'));
$fresh = abs(time() - (int) ($parts[1] ?? 0)) <= 300;
if (! $fresh || ! hash_equals($expected, $parts[2] ?? '')) {
    http_response_code(403);
    exit;
}
// Answer 2xx quickly, then do the work.

يُستخدم الأسلوب نفسه للعناوين المنشأة عبر API، راجع Webhooks.

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

• تخرج الإرسالات خلال نحو دقيقة من الحدث، بحد 50 في الدقيقة لكل شركة.
• يجب أن يرد عنوانك بحالة 2xx خلال 5 ثوانٍ، ولا تُتبع التحويلات.
• الإرسال الفاشل يُعاد بعد دقيقة، ثم 5 دقائق، ثم 30 دقيقة، ثم ساعتين: 5 محاولات في المجموع، ثم يُعلَّم فشل.
• بعد فشل 10 إرسالات متتالية يُوقف العنوان. أصلح عنوانك ثم اضغط تشغيل.
• يُرسل الحدث مرة واحدة فقط لكل عنوان وحدث وموضوع، حتى لو تكرر.
• الأحداث التي تقع والعنوان موقوف لا تُحفظ له.
• الإرسال الذي يبقى منتظرًا 30 يومًا يُسقط بحالة تُخطي، وكذلك ما مُحيت جهة اتصاله. ويُحفظ سجل الإرسالات 30 يومًا.
• يُفحص العنوان قبل كل إرسال، والعناوين داخل الشبكات الخاصة مرفوضة.

اختبر العنوان

1. أضف عنوانًا تجريبيًا من أداة الأتمتة، أو أداة فحص طلبات تملكها.
2. أرسل نموذج موقع ببيانات جديدة، فيُنشأ عميل محتمل جديد.
3. خلال دقيقة يستقبل عنوانك lead_created، وتعرضه آخر الأحداث في صفحة الإشعارات الصادرة بحالة وصل مع رمز الرد.

حل المشكلات