نظرة عامة
يرسل الـ Webhook طلب HTTP من نوعPOST إلى رابط تختاره كلما حدث شيء في
المشروع. استخدمه للنشر في قناة على Slack، أو لفتح تذكرة في نظامك، أو لبدء
عملية آلية في Zapier.
يُرسل
issue.created مرة واحدة لكل مشكلة، لا مع كل تكرار لها، فلا تُغرق حلقة
الأعطال قناتك.
إضافة Webhook
1
افتح الإعدادات
في المشروع، افتح الإعدادات ← Webhooks و Slack وانقر إضافة Webhook.
تحتاج إلى صلاحية تعديل إعدادات المشروع.
2
اختر الوجهة
- Webhook: أي رابط
https://يمكن الوصول إليه من الإنترنت. يوقّع Lerix كل طلب (انظر أدناه). - Slack: رابط incoming webhook تنشئه في Slack من Apps ← Incoming
Webhooks، ويبدأ بـ
https://hooks.slack.com/. ينشر Lerix رسالة منسّقة فيها رابط يعيدك إلى لوحة التحكم.
3
اختر الأحداث
اختر واحداً على الأقل من
feedback.created وnps.detractor
وissue.created.4
انسخ سرّ التوقيع
في الـ Webhook العام، يظهر سرّ التوقيع (
whsec_...) مرة واحدة فقط بعد
إنشائه مباشرة. احفظه مع إعدادات خادمك. وإن أضعته، احذف الـ Webhook وأضِفه
من جديد لتحصل على سرّ جديد.5
أرسل اختباراً
انقر اختبار لإرسال حدث
webhook.test. تعرض لوحة التحكم رمز الحالة
الذي أجاب به خادمك، أو الخطأ إن تعذّر الوصول إليه.محتوى الطلب
يحمل كل طلب Webhook عام متناً بصيغة JSON بالغلاف نفسه:الحقل data لكل حدث
- feedback.created
- nps.detractor
- issue.created
- webhook.test
email وexternalId وbugId بالقيمة null حين لا تنطبق. وتُضبط
bugId حين يكون التثبيت نفسه قد أبلغ عن خطأ قبيل الملاحظة.data مع الوقت. تجاهل الحقول التي لا تعرفها بدلاً من
رفض الطلب.
التحقق من التوقيع
الترويسةLerix-Signature هي HMAC-SHA256 للطابع الزمني والمتن الخام،
t + "." + body، بمفتاح هو سرّ التوقيع الخاص بالـ Webhook. تحقّق منها قبل أن
تثق بأي طلب:
- قسّم الترويسة عند
,واقرأtوv1. - ارفض الطلب إن ابتعد
tعن ساعتك أكثر من 5 دقائق، فهذا يمنع إعادة إرسال طلب قديم. - احسب
HMAC-SHA256(secret, t + "." + rawBody)بصيغة hex وقارنه بـv1مقارنةً ثابتة الزمن.
الإرسال وإعادة المحاولة
- ينتظر Lerix ردّ خادمك حتى 5 ثوانٍ. أجب بأي رمز
2xxبسرعة، وأنجز العمل البطيء بعد الرد. - عند خطأ في الشبكة أو انتهاء المهلة أو
429أو5xx، يعيد Lerix المحاولة حتى 3 مرات، بعد 2 ثم 10 ثم 30 ثانية. تُوقَّع كل محاولة من جديد بطابع زمني حديث، وتحتفظ بمعرّفLerix-Deliveryنفسه. - لا تُعاد المحاولة مع أي رمز آخر (مثل
400أو404). - لا تُتَّبع عمليات إعادة التوجيه.
- يجب أن يستخدم الرابط
httpsوأن يشير إلى عنوان عام. تُرفض العناوين الخاصة وعناوين الاسترجاع (loopback) والعناوين المحلية للرابط (link-local)، عند حفظ الـ Webhook وعند إرسال كل طلب.
createdAt في المتن إن كان الترتيب
مهماً لك.