الـ Webhooks

ما هي الـ Webhooks؟

الـ Webhooks تسمح لأنظمتك الخارجية بأن تُخطَر لحظياً عند وقوع أحداث داخل Fynchat. أنت تسجّل نقطة نهاية (endpoint) — وهي رابط HTTPS عندك — وتستدعيها المنصّة بطلب POST كلما وقع حدث اشتركت به (رسالة جديدة، طلب، حجز، تذكرة دعم... إلخ).

كل نقطة نهاية تتكوّن من ثلاثة أشياء:

• اسم (اختياري) للتعريف.
• رابط URL يستقبل الأحداث.
• حدث واحد أو أكثر من قائمة الأحداث الثابتة في المنصّة.

عند الإنشاء يولّد النظام Signing Secret يظهر مرّة واحدة، وكل تسليم يُوقّع بـ HMAC-SHA256 حتى تتأكّد أنه فعلاً من Fynchat.

ولكل نقطة نهاية تقدر:

• ترسل نبضة اختبار (Test) متزامنة وتشوف النتيجة فوراً.
• تفتح سجلّ التسليمات وتعيد محاولة الفاشلة.
• تدوّر الـ Secret.
• تفعّل/توقف النقطة أو تحذفها.

تجد الميزة في الإعدادات → التكاملات → 🔔 Webhooks على /settings/integrations?tab=webhooks. الرابط القديم /settings/webhooks يحوّلك إليه تلقائياً. التبويب نفسه ظاهر في كل الباقات، لكن إنشاء النقاط وإدارتها يتطلّب باقة تتضمّن ميزة Webhooks (انظر القسم التالي).

الباقة وحدّ النقاط

ميزة Webhooks محكومة بميزة الباقة webhooks. التبويب يفتح في أي باقة، لكن إذا كانت باقتك لا تتضمّن الميزة تشوف لوحة مقفلة 🔒 مع زر ترقية (/upgrade)، ويكون زر الإنشاء معطّلاً.

أعلى القائمة يظهر عدّاد المستخدَم/الحد الأقصى (مثلاً 2/5) للباقات المحدودة:

إنشاء نقطة نهاية

اضغط زر الإنشاء ليُفتح النموذج، واملأ:

بعد الحفظ تُنشأ النقطة مفعّلة مباشرة، وتظهر لك رسالة: «تم إنشاء Webhook. احفظ الـ Secret الآن — لن يظهر مرّة أخرى.».

الأحداث المدعومة

الأحداث مُجمّعة في عائلات، وتُدقَّق مقابل قائمة ثابتة داخل النظام. اشترك بحدث واحد أو أكثر من القائمة:

الـ Signing Secret والتوقيع

بعد الإنشاء (أو بعد التدوير) يظهر الـ Secret مرّة واحدة فقط في بانر مع زر نسخ وتحذير بأنه لن يظهر ثانيةً — احفظه فوراً. صيغته whsec_ متبوعة بـ 48 حرفاً عشوائياً، وهو مخزّن كحقل مخفي لا يظهر أبداً في القوائم.

كل تسليم (وكذلك نبضة الاختبار) يُوقّع بـ HMAC-SHA256 لجسم الطلب باستخدام الـ Secret، ويحمل هذه الترويسات:

تحقّق من التوقيع قبل أي معالجة. مثال بـ PHP:

$body = file_get_contents('php://input');
$sig  = $_SERVER['HTTP_X_FYNTRA_SIGNATURE']; // "sha256=..."
$expected = 'sha256=' . hash_hmac('sha256', $body, $YOUR_SIGNING_SECRET);
if (!hash_equals($expected, $sig)) { http_response_code(401); exit; }

تدوير الـ Secret

زر تدوير الـ Secret يطلب تأكيداً، ثم يولّد Secret جديداً ويعرضه مرّة واحدة في بانر. تُسجَّل العملية في سجلّ تدقيق الحساب كحدث webhook.secret_rotated. بعد التدوير حدّث الـ Secret في نظامك فوراً.

اختبار نقطة النهاية (Test)

زر Test يرسل طلب POST متزامناً إلى رابطك يحوي {"event":"webhook.test", ...} (نصّه: «هذا اختبار للاتصال من فينترالينك»)، بمهلة 15 ثانية. تظهر النتيجة فوراً في الواجهة:

• رمز استجابة HTTP
• زمن الاستجابة (بالمللي ثانية)
• جسم الرد

الطلب موقّع بنفس الترويسات أعلاه، فهو وسيلة عملية للتأكّد أن نقطتك تستقبل وتتحقّق من التوقيع بشكل صحيح قبل الاعتماد عليها.

سجلّ التسليمات وإعادة المحاولة

خلافاً للاختبار المتزامن، تُرسَل أحداث المنصّة الحقيقية عبر مهمّة في الخلفية (queue). زر السجلّات (Logs) يفتح نافذة تعرض محاولات التسليم، 30 لكل صفحة والأحدث أولاً:

أي تسليم حالته ليست success يظهر بجانبه زر إعادة المحاولة (Retry)، الذي يعيد إرسال نفس الحدث بمعرّفه ونوعه وحمولته الأصلية.

بطاقة نقطة النهاية (عرض فقط)

بطاقة كل نقطة تعرض حالتها وإحصاءاتها:

• الرابط وشارة مفعّلة/متوقفة.
• شارة فشل حمراء تظهر عندما يتجاوز عدّاد الفشل 5.
• حتى 5 رقاقات (chips) للأحداث المشترَك بها، مع مؤشّر +N عند وجود أكثر من ذلك.
• عدّاد نجاح/إجمالي للتسليمات؛ «الإجمالي» = كل التسليمات، و«الفاشلة» = التي أُرسلت لكن لم تُرجِع رمز 2xx.

نصيحة: اجعل نقطتك تُرجِع رمز 2xx بعد الاستلام؛ أي رد خارج نطاق 2xx يُحتسب تسليماً فاشلاً.

التفعيل والإيقاف والحذف

• تفعيل/إيقاف: زر واحد يقلب حالة النقطة، ويتبدّل نصّه حسب الحالة، وتعكسها الشارة على البطاقة. الرسالة: «تم تفعيل Webhook.» أو «تم إيقاف Webhook.».
• حذف: يطلب تأكيداً ثم يحذف النقطة نهائياً. الرسالة: «تم حذف Webhook.».

نصائح سريعة

• احفظ الـ Secret فور ظهوره — لن يظهر مرّة أخرى؛ ولو ضاع، استخدم تدوير الـ Secret.
• تحقّق من X-Fyntra-Signature قبل معالجة أي طلب.
• أرجِع 2xx حتى لا يُحتسب التسليم فاشلاً.
• استخدم زر Test للتأكّد من نقطتك قبل الاعتماد عليها.
• راقب شارة الفشل الحمراء وسجلّ التسليمات، وأعِد محاولة الفاشلة عند الحاجة.