الـ Webhooks الصادرة في نافس CRM: أحداث موقّعة تصل إلى خادمك

متى تستخدم الـ Webhooks الصادرة

عندما يحتاج نظام آخر أن يعرف فور تغيّر سجل في نافس، دون أن يسأل كل دقيقة. أمثلة: مزامنة جهات الاتصال الجديدة مع نظام المحاسبة، أو تحديث مستودع بيانات عند كل تعديل على صفقة، أو حذف سجل من نظام التسويق عند حذفه من نافس.

تختلف هذه الـ Webhooks عن روابط Make و n8n في متجر التطبيقات في ثلاثة أمور: تغطي تسعة أحداث بدلًا من حدث واحد، وكل طلب موقّع، والتسليم الفاشل يُعاد تلقائيًا. لذلك هي الخيار المناسب لأي تكامل تعتمد عليه عملياتكم.

إنشاء Webhook

1. 1

   افتح شاشة الـ Webhooks

   بصفتك مديرًا لمساحة العمل: الإعدادات ← التكاملات ← التطبيقات والواجهات البرمجية ← Webhooks.

2. 2

   أضف Webhook جديدًا

   اضغط «Webhook جديد»، واكتب اسمًا يصف الغرض، ثم الصق في «URL نقطة الوصول» رابط HTTPS عامًا لدى خادمك.

3. 3

   اختر الحدث

   في حقل «الحدث» اكتب اسم حدث واحد، مثل deal.created أو contact.updated، أو نمطًا مثل deal.* لكل أحداث الصفقات، أو * لكل الأحداث. ثم أنشئ الـ Webhook.

4. 4

   احصل على سر التوقيع

   لا تعرض الشاشة إلا آخر 4 أحرف من السر. وللحصول عليه كاملًا أنشئ الاشتراك عبر الواجهة البرمجية بالطلب POST /api/webhook-subscriptions، أو دوّر سر اشتراك قائم بالطلب POST /api/webhook-subscriptions/{id}/rotate-secret؛ ويظهر السر الكامل في الاستجابة مرة واحدة فقط.

5. 5

   راقب التسليم

   تعرض بطاقة كل Webhook نسبة النجاح وعدد التسليمات خلال 24 ساعة ووقت آخر تسليم، مع زري الإيقاف المؤقت والاستئناف.

الأحداث والبيانات والترويسات

جسم الطلب JSON يحتوي: اسم الحدث event، ووقت الإرسال delivered_at، ومعرّف التسليم delivery_id، وبيانات السجل data مع الحقول التي تغيّرت في أحداث التحديث، ومن قام بالتغيير actor (مستخدم أو النظام).

• X-Naffes-Event: اسم الحدث.
• X-Naffes-Delivery-Id: معرّف التسليم، ويبقى ثابتًا عند إعادة المحاولة، فاستخدمه لمنع المعالجة المكررة.
• X-Naffes-Webhook-Id: معرّف الاشتراك.
• X-Naffes-Signature: بصيغة t=الطابع الزمني,v1=التوقيع.

التوقيع هو HMAC-SHA256 للنص المكوّن من الطابع الزمني ثم نقطة ثم جسم الطلب الخام، بسر الاشتراك. احسبه على البايتات كما وصلت لا على JSON بعد تحليله وإعادة ترميزه، لأن الحروف العربية تصل مهرّبة بصيغة \uXXXX وأي إعادة ترميز تغيّر التوقيع. مثال بلغة Node.js:

const crypto = require('crypto');

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

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

أي استجابة خارج نطاق النجاح تُعدّ فشلًا. يُحاول نافس التسليم حتى 7 مرات إجمالًا: المحاولة الأولى، ثم بعد 30 ثانية، ودقيقتين، و10 دقائق، وساعة، و6 ساعات، و24 ساعة. ويُسجَّل كل تسليم. وإذا انتهى نصف التسليمات الأخيرة أو أكثر بفشل نهائي بعد استنفاد محاولاته، وكان عددها 10 على الأقل، يتوقف الاشتراك تلقائيًا، وتستأنفه من القائمة بعد إصلاح نقطة الوصول.

الحدود

• السر الكامل لا يظهر في الواجهة: التحقق من التوقيع يتطلب الحصول على السر من الواجهة البرمجية عند الإنشاء أو التدوير.
• حدث واحد لكل Webhook من الواجهة: الواجهة البرمجية تقبل قائمة أحداث في اشتراك واحد.
• سجل التسليمات عبر الواجهة البرمجية فقط: GET /api/webhook-subscriptions/{id}/deliveries.
• لا أحداث لغير السجلات الثلاثة: لا شيء للمهام والاجتماعات والملاحظات والتذاكر والفواتير والرسائل.
• لا حدث مخصص لتغيير المرحلة: راقب الحقول المتغيرة في deal.updated، أو استخدم حدث deal.stage_changed المرسل إلى Make و n8n من متجر التطبيقات.
• روابط عامة فقط: تُرفض العناوين الخاصة والداخلية.

أسئلة شائعة