Skip to main content

نظرة عامة

يرسل الـ 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 مؤقتاً دون حذفه، وتعديل رابطه أو أحداثه في أي وقت.

محتوى الطلب

يحمل كل طلب Webhook عام متناً بصيغة JSON بالغلاف نفسه:
ومعه هذه الترويسات:

الحقل data لكل حدث

تكون email وexternalId وbugId بالقيمة null حين لا تنطبق. وتُضبط bugId حين يكون التثبيت نفسه قد أبلغ عن خطأ قبيل الملاحظة.
قد تُضاف حقول جديدة إلى data مع الوقت. تجاهل الحقول التي لا تعرفها بدلاً من رفض الطلب.

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

الترويسة Lerix-Signature هي HMAC-SHA256 للطابع الزمني والمتن الخام، t + "." + body، بمفتاح هو سرّ التوقيع الخاص بالـ Webhook. تحقّق منها قبل أن تثق بأي طلب:
  1. قسّم الترويسة عند , واقرأ t وv1.
  2. ارفض الطلب إن ابتعد t عن ساعتك أكثر من 5 دقائق، فهذا يمنع إعادة إرسال طلب قديم.
  3. احسب HMAC-SHA256(secret, t + "." + rawBody) بصيغة hex وقارنه بـ v1 مقارنةً ثابتة الزمن.
استخدم متن الطلب الخام كما وصل تماماً. فتحليل JSON ثم إعادة تحويله إلى نص يغيّر البايتات ويُفسد التوقيع.
لا تُوقَّع طلبات Slack، لأن رابط incoming webhook في Slack هو نفسه السرّ، فاحرص على إبقائه خاصاً.

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

  • ينتظر Lerix ردّ خادمك حتى 5 ثوانٍ. أجب بأي رمز 2xx بسرعة، وأنجز العمل البطيء بعد الرد.
  • عند خطأ في الشبكة أو انتهاء المهلة أو 429 أو 5xx، يعيد Lerix المحاولة حتى 3 مرات، بعد 2 ثم 10 ثم 30 ثانية. تُوقَّع كل محاولة من جديد بطابع زمني حديث، وتحتفظ بمعرّف Lerix-Delivery نفسه.
  • لا تُعاد المحاولة مع أي رمز آخر (مثل 400 أو 404).
  • لا تُتَّبع عمليات إعادة التوجيه.
  • يجب أن يستخدم الرابط https وأن يشير إلى عنوان عام. تُرفض العناوين الخاصة وعناوين الاسترجاع (loopback) والعناوين المحلية للرابط (link-local)، عند حفظ الـ Webhook وعند إرسال كل طلب.
لا يُضمن وصول الطلبات بالترتيب. استخدم createdAt في المتن إن كان الترتيب مهماً لك.