إعداد واحدة
1
أضف نقطة النهاية
التكاملات ← Webhooks ← نقطة نهاية جديدة. أعطها اسمًا ورابط
https:// متاحًا علنًا.2
اختر أحداثك
حدّد الأحداث التي تريدها. ولكل حدث يمكنك أيضًا تحديد الحقول التي تحملها الحمولة — راجع
اختيار الحقول.
3
احفظ مفتاح التوقيع
يُعرض مرة واحدة عند الإنشاء، ويبدأ بـ
whsec_. وتحتاجه
للتحقق من التوقيعات. خزّنه في مدير الأسرار لديك قبل إغلاق النافذة.4
أرسل اختبارًا
استخدم إرسال اختبار في صفحة نقطة النهاية. فهو يمر بمسار التسليم الحقيقي — التوقيع نفسه
والتسجيل نفسه — لذا فالاختبار الذي يصل يثبت أن الإعداد يعمل.
الأحداث
تعديل مرحلة عميل محتمل يُطلق كلا الحدثين
lead.updated وlead.stage.changed. اشترك في ما
تقصده فعلًا — فأخذ الاثنين يعني معالجة كل نقلة مرتين.وlead.won وlead.lost يتبعان علامتَي الربح/الخسارة على مراحل مسارك لا اسم المرحلة. فإن غيّرت
اسم «رابح» إلى «مغلقة — موقّعة»، فستظل تعمل.الحمولة
كل عملية تسليم لها المغلّف نفسه. ولا يختلف سوىdata بحسب الحدث:
و
source يستحق الاستخدام إذا كان سير عملك يكتب مجددًا داخل لينكياسوفت: فهو يتيح لك تمييز التغيير
الذي أحدثته أتمتتك من الذي أحدثه إنسان، وهكذا تتجنب الحلقات المفرغة.
اختيار الحقول المرسلة
لكل حدث مجموعة حقول، وأنت تختار ما نُضمّنه. أزل تحديد أي شيء لا يحتاجه النظام المستقبِل — وخصوصًاtext وcustomer_phone وemail، فهي أقل الحقول التي تود بقاءها في سجلات أداة طرف ثالث.
وترك كل الحقول محددة ليس كسردها واحدًا واحدًا. فتحديد الكل يعني «أرسل ما يحمله هذا الحدث»،
فيُضمَّن أي حقل نضيفه لاحقًا تلقائيًا. أما إن أزلت تحديد واحد فقط، فستحصل على المجموعة التي اخترتها
بالضبط ولا شيء جديد.
التحقق من التوقيع
كل طلب يحمل هذه الترويسات:
و
v1 هو HMAC-SHA256 بمفتاح التوقيع لديك، على النص
`${t}.${rawBody}` — الطابع الزمني، ثم نقطة حرفية، ثم جسم الطلب الخام.
timingSafeEqual أو compare_digest أو hash_equals — لا
بـ==.
الطابع الزمني داخل النص الموقّع عمدًا. فتوقيع الجسم وحده كان سيجعل كل عملية تسليم تستقبلها قابلة
لإعادة التشغيل من أي شخص التقط واحدة، إلى الأبد. وفحص
t مقابل هامش تسامح هو النصف الذي يجعله
مفيدًا، فلا تتخطاه.إعادة المحاولة
رُد بـ2xx ونعتبر التسليم منجزًا. وأي شيء آخر:
وإعادات المحاولة تتباعد: 30 ثانية، دقيقتان، 10 دقائق، ساعة، 6 ساعات — خمس محاولات على مدى
ثماني ساعات تقريبًا، ثم نتوقف. وكل محاولة تظهر في السجل برقم
X-Linkia-Attempt خاص بها، وكل
محاولات التسليم الواحد تتشارك id المغلّف نفسه.
عشرون إخفاقًا متتاليًا تعطّل نقطة النهاية. فنتوقف عن استدعائها، وتعرض الصفحة السبب، وتتوقف
الأحداث عن الاصطفاف لها. وهذا موجود حتى لا يولّد رابط اختبار مهجور عمليات تسليم فاشلة إلى الأبد.
أصلح نقطة النهاية واضغط تفعيل من جديد — فذلك يصفّر العدّاد. ولا يُعاد إرسال شيء تلقائيًا؛
استخدم السجل لإعادة إرسال ما يهم.
سجل التسليم
تحتفظ كل نقطة نهاية بـآخر 300 محاولة، مع الجسم الذي أرسلناه بالضبط، وأول 2 كيلوبايت من استجابتك، ورمز الحالة، والمدة المستغرقة. افتح أي منها لرؤية الطلب والاستجابة جنبًا إلى جنب، أو اضغط أيقونة الإعادة لإرسالها ثانية. أما الإجماليات الكلية — كم طلبًا أرسلنا وكم فشل — فتُحسب منفصلة ولا تتأثر بحد الـ 300 صفًا.السجل أداة تصحيح لا أرشيف. فعلى نقطة نهاية مزدحمة قد تستغرق 300 محاولة أقل من ساعة. وإن كنت
تحتاج تاريخًا دائمًا، فسجّل عمليات التسليم لديك مفهرسة بـ
id المغلّف.الترويسات المخصصة
إذا كانت نقطة نهايتك خلف وسيط يريد ترويسة خاصة به، فأضفها من إعدادات نقطة النهاية. أما الترويسات التي نضبطها نحن —Content-Type وUser-Agent وكل ترويسة X-Linkia-* — فلا يمكن تجاوزها، لأن
ترويسة مخصصة تستطيع استبدال التوقيع ستجعل تزوير عمليات التسليم أمرًا تافهًا.
تدوير المفتاح
تدوير المفتاح في صفحة نقطة النهاية يصدر مفتاحًا جديدًا ويعرضه مرة واحدة.أمور تراقبها في الإنتاج
نقطة النهاية البطيئة تكلّفك أحداثًا لا تكلّفنا. فنحن ننتظر 10 ثوانٍ. وإذا كان معالجك يؤدي عملًا حقيقيًا — استدعاء واجهات أخرى، أو الكتابة في قاعدة بيانات بطيئة — فرُد بـ2xx فورًا وعالج في
الخلفية. فالمعالج الذي يرد في 11 ثانية يبدو مطابقًا لمعالج متوقف.
لا تُرجع 4xx لمشكلاتك أنت. فـ422 بسبب تحقق مفرط الصرامة نهائي من جانبنا: لن نعيد المحاولة،
والحدث يضيع. أرجع 5xx لأي شيء تريد محاولة أخرى له.
عمليات التسليم الاختبارية تبدو كالحقيقية. فـwebhook.test يصل عبر المسار نفسه بتوقيع صالح.
عالج اسم الحدث أو تجاهله؛ ولا تفترض أن كل عملية تسليم حدث حقيقي في نظامك.
