webhooks الصادرة
في حين تستقبل قناة webhook الواردة أحداثًا خارجية لمعالجتها، تقوم العقدة webhook_action بالعكس: فهي تُرسل طلب HTTP نحو أنظمتك من أي نقطة في الـpipeline — وهي ما يعادل وحدات « HTTP » في Make أو « Webhooks » في Zapier.
لماذا
من المرجّح أنّ لديك فعلًا:
- نظام تنبيهات (PagerDuty، Opsgenie، Slack).
- أداة ITSM (Jira، ServiceNow) لإدارة التذاكر.
- لوحة معلومات مخصّصة تجمّع حالتك التشغيلية.
بدلًا من مطالبة هذه الأنظمة باستطلاع betool، دَعْ الـpipelines الخاصة بك تُشعِرها: ضع عقدة webhook_action في نقطة الرسم البياني التي يقع فيها الحدث (بريد مُصنَّف، مرشِّح تمّ اجتيازه، تقرير مُجدوَل…). وبالجمع مع قناة الجدولة، فهي أيضًا أساس الدفع الدوري نحو أنظمتك.
تهيئة العقدة
| الحقل | الدور |
|---|---|
url | عنوان URL الهدف (قابل للقولبة) |
method | GET / POST (الافتراضي) / PUT / PATCH / DELETE |
headers / query | قواميس {الاسم: القالب} |
body_mode | none / json (الافتراضي) / form / raw / mapper / multipart |
body_template | قالب الـbody (الأوضاع json / form / raw) |
mapping_spec | بناء الـbody عبر الـpayload mapper (مُوصى به) — العمق، المصفوفات، التحويلات |
auth_mode | none (الافتراضي) / bearer / basic / api_key_header / oauth2 (client credentials) |
auth_config | معاملات وضع المصادقة: {token}، {user, password}، {header, value} أو {credential_id} |
timeout_ms | الافتراضي 30 000 ms |
retry_count | عدد مرات إعادة المحاولة (الافتراضي 0، الحدّ الأقصى 10)، مع تراجع أسّي |
accepted_statuses | رموز HTTP المعتبَرة نجاحًا (الافتراضي: 200، 201، 202، 204) |
output_key | مفتاح التدفّق الذي تُكتَب فيه الاستجابة (الافتراضي webhook.response) |
القولبة (Templating)
يُدرِج كلٌّ من URL والـheaders والـquery والـbody مفاتيحَ التدفّق بالصيغة {المسار}:
{
"event": "order_qualified",
"order_id": "{webhook.payload.order_id}",
"verdict": "{exchange.result}"
}
المصادقة
- تُخزَّن بيانات اعتماد الأوضاع
bearer/basic/api_key_headerفي تهيئة العقدة: فهي تبقى مرئية للأعضاء الذين يستطيعون فتح هذا الـpipeline. - في الوضع
oauth2(client credentials)، لا تحمل العقدة سوى مرجع لبيانات الاعتماد؛ ويقيم السرّ في مخزن OAuth الخاص بالمؤسسة، ولا يُعاد أبدًا عند القراءة، ويُحصَل على الرمز (ثم يُجدَّد) عند التنفيذ. وهو الوضع المفضَّل لسرّ حسّاس.
إرسال الملفات (multipart)
يُرسل الوضع multipart (RFC 7578) الحقول النصية والمرفقات في الطلب نفسه — للشركاء الذين لا يقبلون إلا multipart/form-data. يُشار إلى الملفات بمفتاحها في مخزن الكائنات (object store) وتُعاد قراءتها لحظة الإرسال (20 ملفًا و25 MB كحدّ أقصى)؛ ويُرفَض أي مفتاح خارج نطاق مؤسستك، ويُتخلّى عن أي إرسال ينقصه مرفق بدل إرساله مبتورًا.
إعادة المحاولة والأخطاء
- تؤدّي حالة خارج
accepted_statusesأو انتهاء المهلة أو خطأ شبكة إلى إعادة المحاولة مع تراجع أسّي (0.5 ث، 1 ث، 2 ث، 4 ث…)، حتىretry_countإعادة محاولة. - تُكتَب الاستجابة (
status،headers،body) تحتoutput_key، مع مفتاحerrorبعد استنفاد إعادات المحاولة: يمكن للعُقد اللاحقة قراءة النتيجة وإطلاق معالجة احتياطية عند الفشل. والنتيجة ظاهرة في السجلّ. - لا إرسال مزدوج: إذا أُعيد تشغيل التنفيذ (استئناف بعد إعادة نشر، إعادة محاولة من الطابور)، فإنّ الاستدعاء الذي سبق أن قبله نظامك لا يُعاد إرساله.
إثبات المصدر لدى المُستقبِل
تحمل طلبات webhook_action المصادقة التي تهيّئها أنت (auth_mode): وهي التي تُثبت المصدر لدى نظامك. وللاتجاه المعاكس — التحقّق من توقيع ما يستقبله betool — راجع webhook الواردة.