تخطَّ إلى المحتوى
تسجيل الدخولاطلب حساب

Webhooks الصادرة

الـwebhook العامّ يرسل POST بحمولة JSON موقّعة لنقطتك أنت، كل ما انطلق حدث مشترَك فيه على المشروع: ملاحظة جديدة، إسناد، منشن، تغيير حالة أو أولوية، حلّ، أو ربط تقرير بتذكرة متتبّع. وهذا مسار التسليم للأتمتة، أو لجسر مخصّص، أو لأي خدمة uMarker ما تتكامل معها مباشرة.

هذي الصفحة مرجع المطوّر لـالحمولة وتوقيعها. أمّا ربط الـwebhook وتوجيهه لمشروع فـشوف القنوات والتوجيه.

الـwebhook يستقبل اللي يشترك فيه المسار من هذي الأحداث:

الحدث متى ينطلق
new_feedback تُرسَل ملاحظة جديدة للمشروع، ومنها اللي تُدخَل عبر الـREST API.
assigned يُسنَد التقرير لعضو.
mentioned يُذكَر عضو بـ@ في تعليق.
status_change تتغيّر حالة التقرير لأي حالة غير resolved.
priority تتغيّر أولوية التقرير.
resolved تتغيّر حالة التقرير لـresolved، أو يُعلَّم دبوس فيه بـ«تمّ».
issue_linked يُربط التقرير بـتذكرة متتبّع خارجية.

ولأشغال التكامل، new_feedback وissue_linked غالباً هما اللي تبغاهما: يخلّون نظاماً خارجياً يتفاعل مع وصول التقارير، ومع تحوّلها لشغل في المتتبّع.

uMarker ترسل POST لنقطتك بجسم JSON وبهذي الترويسات:

POST /your/endpoint HTTP/1.1
Content-Type: application/json
X-uMarker-Event-Id: 6f1b2c9e-4a7d-4a1e-9c33-0e7b0a2f51dd
X-uMarker-Signature: t=1751362500,v1=8f43a1c9d0…e7

X-uMarker-Event-Id هي نفس قيمة id اللي بالجسم. حطّيناها بترويسة كمان عشان يقدر المستقبِل يمنع التكرار قبل ما يحلّل جسماً يمكن يرفضه أصلاً.

الجسم كائن JSON مختصر يوصف الحدث والتقرير المتأثّر:

حمولة الـwebhook
{
"id": "6f1b2c9e-4a7d-4a1e-9c33-0e7b0a2f51dd",
"event": "issue_linked",
"account_id": 3,
"project": { "id": 7, "name": "Checkout" },
"feedback": {
"id": 84,
"status": "in_progress",
"url": "https://app.umarker.com/s/8f2c…/feedback/84"
},
"from": null,
"to": null,
"timestamp": "2026-07-01T09:15:00+00:00"
}
الحقل النوع الوصف
id نصّ UUID يعرّف هذا الحدث، وثابت عبر كل إعادة محاولة. امنع التكرار بناءً عليه.
event نصّ نوع الحدث: واحد من السبعة فوق، أو test للإرسال التجريبي.
account_id عدد صحيح معرّف الحساب المالك.
project.id عدد صحيح معرّف المشروع.
project.name نصّ اسم المشروع.
feedback.id عدد صحيح معرّف التقرير المتأثّر.
feedback.status نصّ حالة التقرير الحالية.
feedback.url نصّ رابط باللوحة يفتح التقرير.
from نصّ | null الحالة السابقة. تنملأ مع status_change، ومع حدث resolved اللي جاي من تغيير حالة. وnull بأي حدث ثاني.
to نصّ | null الحالة الجديدة، بنفس الحدثين. ومع حدث priority يحمل الأولوية الجديدة بدل الحالة (none أو low أو medium أو high أو urgent). وnull بأي حدث ثاني.
timestamp نصّ وقت وقوع الحدث بصيغة ISO 8601، مو وقت المحاولة الحالية.

ومع status_change، يحمل from وto الانتقال:

حمولة status_change
{
"id": "b90d7a41-2f6c-4f0e-8d2a-1c5f9a3e77b2",
"event": "status_change",
"account_id": 3,
"project": { "id": 7, "name": "Checkout" },
"feedback": { "id": 84, "status": "resolved", "url": "https://app.umarker.com/s/8f2c…/feedback/84" },
"from": "in_progress",
"to": "resolved",
"timestamp": "2026-07-01T11:02:00+00:00"
}

والحلّ يحمل نفس الزوج، بس يوصلك كحدث resolved مو status_change — from: "in_progress" وto: "resolved". والاستثناء حدث resolved اللي ينطلق من تعليم دبوس بـ«تمّ»، فهنا الاثنين null. ومع حدث priority، to يحمل مستوى الأولوية الجديد وfrom يكون null.

الحمولة تحمل مراجع مو محتوى عن قصد: معرّف ورابط، لا كلام المُبلِّغ ولا بيانات حساب ثاني ولا أي اعتماد. ولو تبغى أكثر، اجلب التقرير كاملاً من الـREST API أو افتح رابط اللوحة.

كل طلب webhook موقّع، عشان يقدر مستقبِلك يثبت إنه فعلاً جاي من uMarker وما انعدّل بالطريق. والتوقيع في ترويسة X-uMarker-Signature:

X-uMarker-Signature: t=<unix-timestamp>,v1=<signature>
  • t: الطابع الزمني Unix (بالثواني) وقت التوقيع.
  • v1: التوقيع، وهو HMAC-SHA256 (hex) على السلسلة <t>.<raw-body>، بمفتاح هو سرّ توقيع القناة.

يعني uMarker تحسب:

signature = HMAC_SHA256( key = <channel secret>, message = "<t>.<raw request body>" )

والتوقيع يغطّي البايتات بالضبط كما أُرسلت. وعشان تتحقّق، أعد حساب نفس الـHMAC وقارن.

  1. اقرأ ترويسة X-uMarker-Signature وقسّمها على , إلى t=… وv1=….

  2. خذ جسم الطلب الخام غير المحلَّل: البايتات بالضبط كما وصلت. لا تعيد تسلسل الـJSON بعد تحليله؛ أي تغيير بالمسافات أو بترتيب المفاتيح يكسر المطابقة.

  3. احسب HMAC-SHA256 للسلسلة `${t}.${rawBody}` بمفتاح هو سرّ توقيع القناة، ورمّزها hex.

  4. قارن قيمتك بـv1 بمقارنة ثابتة الزمن. التطابق يثبت المصدر والسلامة؛ وعدم التطابق يعني ترفض الطلب.

  5. واختيارياً، ارفض الطلب لو كان t بعيداً عن ساعتك (مثلاً أكثر من دقائق) عشان تحدّ من إعادة التشغيل.

verify.js
const crypto = require('crypto');
// `rawBody` MUST be the exact bytes received (e.g. express.raw()), not a re-stringified object.
function verifyUMarker(rawBody, header, secret) {
const parts = Object.fromEntries(
header.split(',').map((kv) => kv.split('='))
);
const { t, v1 } = parts;
if (!t || !v1) return false;
const expected = crypto
.createHmac('sha256', secret)
.update(`${t}.${rawBody}`)
.digest('hex');
// Constant-time compare; guard against length mismatch.
const a = Buffer.from(v1, 'hex');
const b = Buffer.from(expected, 'hex');
return a.length === b.length && crypto.timingSafeEqual(a, b);
}

السرّ قيمة من 40 محرف تُسكّ وقت إنشاء اتصال الـwebhook. مشفّر عند التخزين، ومستثنى من التسلسل الافتراضي للقناة عشان ما يركب مع استجابة ما لها علاقة فيه.

ويُرجَع بس لمن يقدر يدوّره: اللي يملك integrations.rotatechannel. ربط قناة، وتغيير وجهتها، وتدوير سرّها ترجّعه في استجابتها لمن يملك هالصلاحية، وقائمة التكاملات ما تعرضه لغيره — فالدور اللي يقدر يربط قناة أو يغيّر وجهتها لكن ما يدوّر سرّها ما يقراه أبداً. وغير كذا، الطرفان فقط (uMarker ومستقبِلك) يمسكونه.

ولو تسرّب، دوّره من صفحة التكاملات. والتدوير قطع حادّ: لحظة ما تدوّر، التسليمات تُوقَّع بالسرّ الجديد والقديم يوقف يتحقّق. حدّث مستقبِلك بالسرّ الجديد قبل ما ينطلق الحدث اللي بعده. شوف القنوات والتوجيه.

التسليم وإعادة المحاولة والفشل

Section titled “التسليم وإعادة المحاولة والفشل”

ما يعطّل شي

كل تسليم حدث يمرّ بطابور، فما يعطّل أبداً الأكشن اللي أطلقه. وكل وجهة تُسلَّم لحالها: فشل وحدة ما يأثّر على الثانية ولا على بريدك. وإرسال اختبار هو الاستثناء الوحيد — يشتغل جوّه طلبك عشان يرجّع لك النتيجة الحقيقية.

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

مهلة 10 ثوانٍ، وبعدها لين ثلاث محاولات بتراجع 10 ثوانٍ ثم 30، قبل ما يُوسَم الاتصال متعثّراً. وأول تسليم ناجح يمسح الوسم.

ما يتبع إعادة التوجيه

التسليم يرفض يتبع إعادة التوجيه ويحلّ IPv4 بس، فنقطة عامة ما تقدر تسوّي 302 ولا تمرّر عنواناً غير مفحوص وقت الإرسال.

‏HTTPS عامّ فقط

النقاط تُفحص وقت الحفظ: https بس، ولازم مضيفها يحلّ لعنوان عام. والعناوين الخاصة والمحلّية وعناوين الميتاداتا مرفوضة.

ردّ بحالة 2xx بسرعة عشان تؤكّد الاستلام. وأي شي غيرها (ومنها إعادة التوجيه 3xx) يُحتسب فشلاً وتُعاد المحاولة؛ وبعد سقف المحاولات يُوسَم الاتصال متعثّراً باللوحة لين أول تسليم ناجح.