Skip to main content
بدل استطلاعنا بحثًا عن التغييرات، سجّل نقطة نهاية فنرسل إليها POST فور وقوع الأحداث. وصول رسالة، أو بلوغ عميل محتمل مرحلة «رابح»، أو تعليق على منشور فيسبوك — كل منها يصبح طلب HTTP إلى رابط تتحكم فيه. وهذا ما تريده إن كنت تشغّل n8n أو Zapier أو Make أو شيئًا كتبته بنفسك. راجع دليل n8n لمثال عملي. تُضبط الـ Webhooks داخل التطبيق لا عبر الـ API. اذهب إلى التكاملات ← Webhooks. فنقطة النهاية مكان نرسل إليه بيانات عملائك، لذا فإنشاؤها إجراء إداري عمدًا لا شيء يستطيع مفتاح API فعله.

إعداد واحدة

1

أضف نقطة النهاية

التكاملات ← Webhooks ← نقطة نهاية جديدة. أعطها اسمًا ورابط https:// متاحًا علنًا.
2

اختر أحداثك

حدّد الأحداث التي تريدها. ولكل حدث يمكنك أيضًا تحديد الحقول التي تحملها الحمولة — راجع اختيار الحقول.
3

احفظ مفتاح التوقيع

يُعرض مرة واحدة عند الإنشاء، ويبدأ بـwhsec_. وتحتاجه للتحقق من التوقيعات. خزّنه في مدير الأسرار لديك قبل إغلاق النافذة.
4

أرسل اختبارًا

استخدم إرسال اختبار في صفحة نقطة النهاية. فهو يمر بمسار التسليم الحقيقي — التوقيع نفسه والتسجيل نفسه — لذا فالاختبار الذي يصل يثبت أن الإعداد يعمل.
يجب أن يشير الرابط إلى عنوان عام. فالنطاقات الخاصة وlocalhost وعناوين الرابط المحلي وعناوين بيانات السحابة الوصفية مرفوضة، عند حفظ نقطة النهاية وفي كل عملية تسليم أيضًا — فاسم المضيف الذي يُعاد توجيهه للداخل لاحقًا يتوقف عن العمل بدل أن يصبح مدخلًا إلى شبكتنا.تختبر محليًا؟ استخدم نفقًا مثل ngrok أو رابط الاختبار الخاص بـ n8n، لا http://localhost.

الأحداث

تعديل مرحلة عميل محتمل يُطلق كلا الحدثين lead.updated وlead.stage.changed. اشترك في ما تقصده فعلًا — فأخذ الاثنين يعني معالجة كل نقلة مرتين.وlead.won وlead.lost يتبعان علامتَي الربح/الخسارة على مراحل مسارك لا اسم المرحلة. فإن غيّرت اسم «رابح» إلى «مغلقة — موقّعة»، فستظل تعمل.

الحمولة

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

اختيار الحقول المرسلة

لكل حدث مجموعة حقول، وأنت تختار ما نُضمّنه. أزل تحديد أي شيء لا يحتاجه النظام المستقبِل — وخصوصًا text وcustomer_phone وemail، فهي أقل الحقول التي تود بقاءها في سجلات أداة طرف ثالث. وترك كل الحقول محددة ليس كسردها واحدًا واحدًا. فتحديد الكل يعني «أرسل ما يحمله هذا الحدث»، فيُضمَّن أي حقل نضيفه لاحقًا تلقائيًا. أما إن أزلت تحديد واحد فقط، فستحصل على المجموعة التي اخترتها بالضبط ولا شيء جديد.

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

كل طلب يحمل هذه الترويسات: وv1 هو HMAC-SHA256 بمفتاح التوقيع لديك، على النص `${t}.${rawBody}` — الطابع الزمني، ثم نقطة حرفية، ثم جسم الطلب الخام.
وقّع الجسم الخام كما ورد تمامًا. فإذا حلّل إطار العمل لديك الـ JSON وأعدت أنت تسلسله قبل التجزئة، سيختلف ترتيب المفاتيح أو المسافات وستفشل كل التوقيعات. ومعظم أطر العمل تحتاج أن تُخبرها بالاحتفاظ بالجسم الخام.
قارن البصمات بدالة ثابتة الزمن — timingSafeEqual أو compare_digest أو hash_equals — لا بـ==.
الطابع الزمني داخل النص الموقّع عمدًا. فتوقيع الجسم وحده كان سيجعل كل عملية تسليم تستقبلها قابلة لإعادة التشغيل من أي شخص التقط واحدة، إلى الأبد. وفحص t مقابل هامش تسامح هو النصف الذي يجعله مفيدًا، فلا تتخطاه.

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

رُد بـ2xx ونعتبر التسليم منجزًا. وأي شيء آخر: وإعادات المحاولة تتباعد: 30 ثانية، دقيقتان، 10 دقائق، ساعة، 6 ساعات — خمس محاولات على مدى ثماني ساعات تقريبًا، ثم نتوقف. وكل محاولة تظهر في السجل برقم X-Linkia-Attempt خاص بها، وكل محاولات التسليم الواحد تتشارك id المغلّف نفسه.
التسليم مرة واحدة على الأقل. فعطل شبكة بعد نجاح معالجك وقبل وصول 2xx إلينا يعني أنك سترى الحدث نفسه مجددًا. وإذا كانت إعادة المعالجة ستضاعف خصمًا ماليًا، أو ترسل رسالة مكررة، أو تنشئ سجلًا ثانيًا، فأزل التكرار بالاعتماد على id المغلّف — فهو ثابت عبر كل المحاولات.
عشرون إخفاقًا متتاليًا تعطّل نقطة النهاية. فنتوقف عن استدعائها، وتعرض الصفحة السبب، وتتوقف الأحداث عن الاصطفاف لها. وهذا موجود حتى لا يولّد رابط اختبار مهجور عمليات تسليم فاشلة إلى الأبد. أصلح نقطة النهاية واضغط تفعيل من جديد — فذلك يصفّر العدّاد. ولا يُعاد إرسال شيء تلقائيًا؛ استخدم السجل لإعادة إرسال ما يهم.

سجل التسليم

تحتفظ كل نقطة نهاية بـآخر 300 محاولة، مع الجسم الذي أرسلناه بالضبط، وأول 2 كيلوبايت من استجابتك، ورمز الحالة، والمدة المستغرقة. افتح أي منها لرؤية الطلب والاستجابة جنبًا إلى جنب، أو اضغط أيقونة الإعادة لإرسالها ثانية. أما الإجماليات الكلية — كم طلبًا أرسلنا وكم فشل — فتُحسب منفصلة ولا تتأثر بحد الـ 300 صفًا.
السجل أداة تصحيح لا أرشيف. فعلى نقطة نهاية مزدحمة قد تستغرق 300 محاولة أقل من ساعة. وإن كنت تحتاج تاريخًا دائمًا، فسجّل عمليات التسليم لديك مفهرسة بـid المغلّف.

الترويسات المخصصة

إذا كانت نقطة نهايتك خلف وسيط يريد ترويسة خاصة به، فأضفها من إعدادات نقطة النهاية. أما الترويسات التي نضبطها نحن — Content-Type وUser-Agent وكل ترويسة X-Linkia-* — فلا يمكن تجاوزها، لأن ترويسة مخصصة تستطيع استبدال التوقيع ستجعل تزوير عمليات التسليم أمرًا تافهًا.

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

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

أمور تراقبها في الإنتاج

نقطة النهاية البطيئة تكلّفك أحداثًا لا تكلّفنا. فنحن ننتظر 10 ثوانٍ. وإذا كان معالجك يؤدي عملًا حقيقيًا — استدعاء واجهات أخرى، أو الكتابة في قاعدة بيانات بطيئة — فرُد بـ2xx فورًا وعالج في الخلفية. فالمعالج الذي يرد في 11 ثانية يبدو مطابقًا لمعالج متوقف. لا تُرجع 4xx لمشكلاتك أنت. فـ422 بسبب تحقق مفرط الصرامة نهائي من جانبنا: لن نعيد المحاولة، والحدث يضيع. أرجع 5xx لأي شيء تريد محاولة أخرى له. عمليات التسليم الاختبارية تبدو كالحقيقية. فـwebhook.test يصل عبر المسار نفسه بتوقيع صالح. عالج اسم الحدث أو تجاهله؛ ولا تفترض أن كل عملية تسليم حدث حقيقي في نظامك.