Webhooks (الإشعارات الآلية)

تتيح Webhooks (الإشعارات الآلية) لـ Resool إبلاغ أنظمتك فور حدوث شيء في مساحة العمل. تضيف نقطة استقبال (رابطًا على خادمك) وتختار أحداثًا مثل استلام رسالة أو إنشاء جهة اتصال أو كسب صفقة. وفي كل مرة يقع فيها أحد هذه الأحداث يرسل Resool طلب POST موقّعًا عبر HTTPS يحمل التفاصيل، ويعيد المحاولة إن لم يرد خادمك، ويحتفظ بسجل لآخر عمليات الإرسال. استخدمها لمزامنة البيانات مع نظام CRM أو مستودع البيانات، أو لتشغيل الأتمتة الخاصة بك، أو لتنبيه أداة أخرى لحظيًا.

#قبل أن تبدأ

• يستطيع المالك والمسؤول فقط إضافة نقاط الاستقبال وإدارتها.
• يجب أن تكون نقطة الاستقبال عنوانًا عامًّا يبدأ بـ https. تُرفض العناوين على الشبكات الخاصة.

#الأحداث التي يمكنك إرسالها

#كيفية إضافة نقطة استقبال

1. انتقل إلى الإعدادات › التطبيقات وافتح تبويب أدوات المطورين.
2. انقر ربط (أو إدارة) على بطاقة Webhooks. تفتح صفحة Webhooks.
3. انقر إضافة نقطة استقبال.
4. املأ النموذج:
   • عنوان نقطة الاستقبال: رابط https العام الخاص بك.
   • الوصف (اختياري): ملاحظة لفريقك، مثل "مستودع البيانات".
   • الأحداث المرسلة: حدّد حدثًا واحدًا على الأقل.
5. انقر إضافة نقطة الاستقبال.

مكان لقطة الشاشة

الإعدادات › التطبيقات › أدوات المطورين › Webhooks › إضافة نقطة استقبال

نافذة "إضافة نقطة استقبال" وفيها عنوان https ووصف وقائمة الأحداث المرسلة مع تحديد استلام رسالة وإنشاء جهة اتصال وكسب صفقة.

الملف: screenshots/ar/webhooks-add-endpoint.png

1. تعرض نافذة انسخ مفتاح التوقيع المفتاح السري لنقطة الاستقبال. انسخه واحفظه على خادمك، فهو ما تستخدمه للتحقق من أن الطلبات صادرة فعلًا من Resool. انقر تم.

يمكنك نسخ المفتاح مرة أخرى لاحقًا من قائمة نقطة الاستقبال.

#شكل كل طلب

يرسل Resool طلب POST بمحتوى JSON وهذه الترويسات:

POST /your/endpoint
Content-Type: application/json
User-Agent: Resool-Webhooks/1.0
Resool-Event: message.received
Resool-Delivery: 7c2f…            (unique per delivery)
Resool-Signature: t=1790990000,v1=5b2c…

{
  "id": "evt_9f1c…",
  "type": "message.received",
  "createdAt": "2026-10-01T10:00:00.000Z",
  "data": {
    "id": "01a0…",
    "conversationId": "01a0…",
    "contactId": "01a0…",
    "channelType": "whatsapp",
    "body": "Hello!",
    "attachments": 0,
    "createdAt": "2026-10-01T10:00:00.000Z"
  }
}

الحقل id يعرّف الحدث، وtype نوعه، وdata يحمل السجل الذي تغيّر.

#كيفية التحقق من التوقيع

تحتوي ترويسة Resool-Signature على طابع زمني بنظام Unix هو t، وعلى v1 وهو قيمة HMAC-SHA256 بالنظام الست عشري للنص "<t>.<raw body>" باستخدام مفتاح التوقيع الخاص بنقطة الاستقبال. احسب القيمة نفسها من محتوى الطلب الخام (قبل تحليل JSON)، وقارنها بمقارنة ثابتة الزمن، وارفض الطلبات التي يزيد عمر طابعها الزمني على 5 دقائق.

import { createHmac, timingSafeEqual } from 'node:crypto';

function verifyResool(rawBody, header, secret) {
  const { t, v1 } = Object.fromEntries(header.split(',').map((p) => p.split('=')));
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
  const expected = createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
  return v1?.length === expected.length && timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}

import hmac, hashlib, time

def verify_resool(raw_body: bytes, header: str, secret: str) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    if abs(time.time() - int(parts["t"])) > 300:
        return False
    signed = parts["t"].encode() + b"." + raw_body
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts.get("v1", ""))

#كيف يعمل الإرسال وإعادة المحاولة

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

#كيفية إدارة نقاط الاستقبال

تعرض كل نقطة استقبال في صفحة Webhooks عنوانها وعدد أحداثها ووصفها. استخدم المفتاح لإيقاف الإرسال مؤقتًا أو استئنافه. وتحتوي قائمة ⋯ على:

• آخر عمليات الإرسال: آخر 50 عملية إرسال مع الحدث والحالة (قيد الانتظار أو تم التسليم أو فشل) وعدد المحاولات والرد. انقر إعادة المحاولة على أي إرسال فاشل لإرساله من جديد.
• إرسال حدث تجريبي: يجدول عينة من أول حدث في نقطة الاستقبال بالمعرّف evt_test، لتختبر نقطة الاستقبال والتحقق من التوقيع.
• نسخ مفتاح التوقيع: ينسخ المفتاح مرة أخرى.
• تعديل نقطة الاستقبال: غيّر العنوان أو الوصف أو الأحداث.
• حذف: أكّد إزالة نقطة الاستقبال؟ ليتوقف إرسال الأحداث إليها.

مكان لقطة الشاشة

الإعدادات › التطبيقات › أدوات المطورين › Webhooks

صفحة Webhooks بنقطتي استقبال: الأولى نشطة وتعرض "3 أحداث · مستودع البيانات"، والثانية عليها الشارة الحمراء "أُوقفت بعد تكرار الفشل"، مع فتح قائمة ⋯ للأولى وفيها آخر عمليات الإرسال، وإرسال حدث تجريبي، ونسخ مفتاح التوقيع، وتعديل نقطة الاستقبال، وحذف.

الملف: screenshots/ar/webhooks-endpoint-list.png

مكان لقطة الشاشة

الإعدادات › التطبيقات › أدوات المطورين › Webhooks › ⋯ › آخر عمليات الإرسال

نافذة آخر عمليات الإرسال وفيها قائمة: عدة عمليات بحالة تم التسليم، وواحدة بحالة فشل مع "3 محاولات" وزر إعادة المحاولة.

الملف: screenshots/ar/webhooks-recent-deliveries.png

تظهر نقاط الاستقبال التي أنشأتها Zapier أو Make أو n8n في القائمة مع عبارة أُضيفت عبر الواجهة البرمجية، وتُزال تلقائيًا عند إيقاف الأتمتة في تلك الأداة.

#الأسئلة الشائعة وحل المشكلات

#أُوقفت نقطة الاستقبال، فكيف أعيد تشغيلها؟

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

#يفشل الإرسال بسبب انتهاء المهلة

ما يمكنك فعله:

• رُدّ بالحالة 200 بمجرد استلام الطلب، ثم عالجه في الخلفية.
• تأكد أن نقطة الاستقبال لا تعيد التوجيه (مثلًا من http إلى https أو إلى رابط ينتهي بشرطة مائلة).

#يفشل التحقق من التوقيع دائمًا

ما يمكنك فعله:

• احسب HMAC على المحتوى الخام كما وصل تمامًا، لا على JSON بعد إعادة تحويله إلى نص.
• استخدم المفتاح من نسخ مفتاح التوقيع لهذه النقطة تحديدًا، فلكل نقطة استقبال مفتاحها.
• تأكد أن ساعة خادمك مضبوطة، لأن الطلبات الأقدم من 5 دقائق يجب أن تُرفض.

#لماذا رُفض عنوان نقطة الاستقبال؟

يجب أن يبدأ العنوان بـ https://، وألا يحتوي على اسم مستخدم أو كلمة مرور، وأن يشير إلى خادم عام لا إلى شبكة خاصة أو محلية.

#هل يمكنني استقبال أحداث قناة واحدة فقط؟

ترسل Webhooks كل أحداث الأنواع المختارة لمساحة العمل كلها. صفِّ الأحداث من جهتك باستخدام حقول data مثل channelType.

#ما التالي؟

• الواجهة البرمجية للمطورين
• Zapier
• Make
• n8n