Orbit
Orbit Webhooks
Webhooks push a signed HTTP POST to a URL of your choosing every time a deployment changes state, so your team hears about a failed build in the channel they already watch instead of finding out…
Webhooks تدفع HTTP POST موقّع إلى عنوان URL من اختيارك في كل مرة تتغير حالة النشر، بحيث يسمع فريقك عن البناء الفاشل في القناة التي يراقبونها بالفعل بدلاً من معرفة ذلك من العميل.
حيث تعيش Webhooks
افتح Orbit، انقر على المشروع، واختر Webhooks ضمن مجموعة Configure في شريط علامات تبويب المشروع. الصفحة بعنوان Webhooks وتصف نفسها بأنها تستقبل إخطارات HTTP POST عند تغيير حالة النشر، مع دعم Slack و Discord و JSON عام.
Webhooks و Hooks أشياء مختلفة وتجلس بجانب بعضها في نفس القائمة. Webhooks الصادرة: Orbit يخبرك بحدوث شيء ما. Deploy hooks الواردة: شيء ما يخبر Orbit بالنشر. لتلك، انظر تشغيل النشر عبر Deploy Hooks.
إضافة Webhook
- في بطاقة Add a webhook، أعطها Label. شيء مثل الوجهة التي ينشر إليها.
- الصق URL. يجب أن يبدأ بـ
https://. - تحت Trigger on، اختر الأحداث التي تريدها.
- انقر على Add webhook.
يتم عرض سر التوقيع مرة واحدة فقط، مباشرة بعد الإنشاء، مع تحذير من أنه لن يتم عرضه مرة أخرى. انسخه قبل أن تغادر الصفحة.
يمكن للمشروع أن يحتفظ بما يصل إلى عشرة webhooks. سيتم رفض إضافة الحادي عشر برسالة تذكر الحد.
الأحداث الخمسة
| الحدث | يطلق عندما |
|---|---|
| Queued | يدخل النشر إلى قائمة الانتظار |
| Building | يبدأ البناء |
| Succeeded | النشر مباشر |
| Failed | البناء أو النشر فشل |
| Cancelled | تم إيقاف النشر قبل الانتهاء |
اختر بتعمد. الاشتراك في جميع الأحداث الخمسة على مشروع مشغول يحول قناة تنبيه مفيدة إلى ضوضاء يصمتها الجميع. بالنسبة لمعظم الفرق، Failed وحده هو نقطة البداية الصحيحة، مع إضافة Succeeded فقط حيث يكون إخطار النشر مفيداً فعلاً، مثل قناة الإنتاج.
Slack و Discord
إذا كان عنوان URL ملخصاً واردة Slack أو webhook Discord، فإن Orbit يكتشفه من عنوان URL وينشئ رسالة منسقة بدلاً من JSON الخام. تقول الصفحة ذلك تحت حقل عنوان URL: يتم اكتشاف عناوين Slack و Discord تلقائياً.
تحمل الرسالة المنسقة اسم المشروع والحدث والفرع والالتزام القصير ووقت البناء وعنوان URL المنشور ونص الخطأ عند حدوث خطأ. يتابع اللون الحدث، لذا فإن بطاقة حمراء في القناة تعني فشل دون أن يقرأ أحد.
لا يوجد شيء آخر مطلوب. أنشئ الملخص الوارد في Slack أو Discord، والصق عنوان URL هنا، واختر أحداثك، وتمت.
Generic JSON Payloads
أي عنوان URL آخر يتلقى جسم JSON. الحقول هي:
| الحقل | المحتويات |
|---|---|
event | واحد من أسماء الأحداث الخمسة، بادئة deployment. |
projectId، projectName، projectSlug | المشروع |
deploymentId | النشر الذي يتعلق به |
gitCommit، gitBranch، gitCommitMessage | الكود الذي يتم نشره |
buildDurationMs | وقت البناء، حيث يكون معروفاً |
deployedUrl | حيث ذهب مباشر |
panelUrl | رابط للخلف إلى KPanel |
errorMessage | موجود عند الفشل |
triggeredAt | ISO 8601 timestamp |
deliveryId | فريد لكل تسليم، للإلغاء |
استخدم deliveryId لجعل نقطتك النهائية idempotent. إذا أعدت محاولة التسليم، أو سبب عطل في الشبكة تكراراً، فإن المعرّف يسمح لك بالتعرف على أنك تعاملت معه بالفعل.
التحقق من التوقيع
يحمل كل تسليم ثلاثة رؤوس:
X-Orbit-Signature-256، HMAC-SHA256 لجسم الطلب الدقيق باستخدام سر التوقيع الخاص بك، منسق كـsha256=متبوعاً بالهضم السادس عشري.X-Orbit-Event، اسم الحدث.X-Orbit-Delivery، معرف التسليم.
تحقق من التوقيع قبل التصرف بناءً على الحمل الأساسي. احسب نفس HMAC عبر بايتات الجسم الخام، وقارن باستخدام مقارنة وقت ثابت بدلاً من مساواة السلسلة.
const expected = 'sha256=' + crypto
.createHmac('sha256', process.env.ORBIT_WEBHOOK_SECRET)
.update(rawBody)
.digest('hex');
if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(received))) {
return res.status(401).end();
}
احسب HMAC عبر جسم الطلب الخام، قبل أي تحليل JSON وإعادة تسلسل. الجسم الذي تم تحليله وتسلسله مرة أخرى عادة ما يكون مختلفاً في البايت، ولن يطابق التوقيع أبداً بغض النظر عن مدى صحة الكود الخاص بك.
اختبار Webhook
يحتوي كل صف webhook على Send test delivery. ينطلق إلى نقطتك النهائية على الفور ويبلغ عن كود HTTP الذي حصل عليه، أو تفاصيل الفشل.
استخدمه مباشرة بعد إضافة webhook، قبل أن تعتمد عليه. قاعدة جدار الحماية أو المسار الذي يقبل GET فقط يكون أسهل في العثور عليه الآن بدلاً من أثناء حادثة.
سجل التسليم
يحمل كل صف شريط sparkbar لآخر سبعة أيام مع عدد التسليم ونسبة النجاح والمدة الوسيطة، بالإضافة إلى آخر وقت تم فيه وتنفيذه ونتيجته.
قم بتوسيع Show delivery history للتسليمات الفردية: الحدث ورمز الاستجابة والمدة ونص الخطأ حيث كان هناك واحد. يمكن إعادة إرسال أي تسليم باستخدام Retry delivery، والذي يبلغ عن الرمز الذي حصل عليه.
انتهاء المهلة الزمنية للتسليمات بعد اثني عشر ثانية. إذا كانت نقطتك النهائية تقوم بعمل بطيء، فأقر بـ 200 أولاً ومعالجة بعد ذلك، بدلاً من إبقاء الاتصال مفتوحاً.
تدوير السر
انقر على Rotate secret. يتم عرض السر الجديد مرة واحدة فقط، والتلميح واضح بأن السر القديم يصبح غير صالح على الفور.
هذا يعني نافذة قصيرة حيث يتم توقيع التسليمات برمز لا تعرفه نقطتك النهائية. خطط له: قم بالتدوير في لحظة هادئة، وحدّث نقطتك النهائية كإجراء تالي جداً.
قم بالتدوير عندما يترك شخص لديه إمكانية الوصول إلى السر، أو إذا تم لصقه في قناة مشتركة أو تذكرة.
التعطيل والحذف
Disable webhook يوقف التسليمات ولكن يبقي التكوين والسجل، والصف يظهر شارة Disabled. هذا هو الخيار الصحيح عندما تكون مراقبة الأنابيب، على سبيل المثال أثناء الترحيل المخطط له الذي سينتج عنه الكثير من الضوضاء.
Delete webhook يزيله بالكامل. استخدم التعطيل إلا إذا كنت متأكداً.
طرق أخرى لكي يتم إخطارك
Webhooks هي الخيار المرن. يجلس اثنان من البدائل الأخف وزناً في Settings:
- Deploy email notifications، مع ثلاثة إعدادات: جميع النشرات أو الفشل فقط أو الإيقاف.
- Notification channels، التي تنشر إلى عنوان URL webhook عند نجاح النشر أو الفشل وتراجعات البناء وتراجعات الحزمة، مع سجل التسليم والزر الخاص بهم.
انظر Orbit Project Settings لكليهما.
استكشاف الأخطاء وإصلاحها
التسليمات تظهر كفشل مع رمز HTTP. أرجعت نقطتك النهائية خطأ. يخبرك الرمز أي: 404 يعني أن المسار خاطئ، و 401 أو 403 عادة يعني أن فحص التوقيع الخاص بك يرفضه، و 500 يعني رميت المعالج.
التسليمات تفشل مع انتهاء المهلة الزمنية. أخذت نقطتك النهائية أكثر من اثني عشر ثانية. أرجع 200 على الفور وقم بالعمل بشكل غير متزامن.
لا يتم تسليم أي شيء على الإطلاق. تحقق من تمكين webhook وأن الحدث الذي توقعته محدد. البناء الذي لم يدخل قائمة الانتظار لا يطلق حدث queued.
التوقيع لا يتحقق أبداً. تقريباً دائماً مشكلة الجسم الخام الموضحة أعلاه. سجل البايتات الدقيقة التي تقوم بـ hash والمقارنة بطولها مع رأس Content-Length.
يتم إرسال عنوان URL الخاص بـ Slack raw JSON. تعيش ملخصات Slack الواردة ضمن hooks.slack.com. عنوان URL مختلف من Slack لن يتم اكتشافه كواحد.
حيث تذهب بعد ذلك
- تشغيل النشر عبر Deploy Hooks للاتجاه الوارد.
- Orbit Project Settings لإخطارات البريد الإلكتروني وقنوات الإخطار.
- Orbit Status Page لإخبار عملائك وليس فريقك فقط.