مشغل Webhook

A webhook lets external systems (GitHub, CI/CD, Lark, IoT, an upstream API) start a workflow execution directly via HTTP POST. Recommended approach: bind the Webhook to an API Key with the WeBHOOK TRIGGER scope and authenticate trigger requests with that Key.

Create a webhook and bind an API Key

1. Under Console s account settings , API key, create a Key and check the scope WEBHOOK_TRIGGER (انظر:مفاتيح ونطاقات API)
2. Create a webhook from the Webhook list or the workflow details page, choose the target work flow, and bind this Key. يحتاج الصانع إلى إذن تحريري على سير العمل، ويجب أن يكون المفتاح المحدد ملكهم

ويمكنكم أيضاً أن تستخدموا نظام تقييم الأداء الإداري (مع جلسة لوجستيات مدمجة):

curl -X POST https://braidrun.com/api/webhooks \
  -H "Authorization: Bearer <console-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "workflowId": "<workflow-id>",
    "name": "GitHub Push Webhook",
    "apiKeyId": "<api-key-id>",
    "variableMapping": {
      "branch": "ref",
      "repo_name": "repo"
    }
  }'

وتشمل الاستجابة جهازا شبكيا فريدا. الزناد هو:

POST https://braidrun.com/api/webhooks/<webhook-id>/trigger

(ويهوك) يعد جدولاً مع خطتك: 3 على (برو)، 10 على الفريق.

تشغيل سير العمل

curl -X POST https://braidrun.com/api/webhooks/<webhook-id>/trigger \
  -H "Authorization: Bearer dyk_<id>_<secret>" \
  -H "Content-Type: application/json" \
  -d '{
    "ref": "refs/heads/main",
    "repo": "my-app"
  }'

ويمكن الموافقة على بيانات الاعتماد بثلاثة طرق يفحصها الخادم بهذا الترتيب:

Authorization: Bearer dyk_<id>_<secret>      # 推荐
X-API-Key: dyk_<id>_<secret>                  # 无法自定义 Authorization 头时
POST .../trigger?api_key=dyk_<id>_<secret>    # 仅限无法设置 header 的场景

عوائد الزناد الناجحة:

{
  "executionId": "exec_a3b9c8...",
  "webhookId": "<webhook-id>",
  "workflowId": "<workflow-id>",
  "status": "PENDING",
  "startedAt": 1735632891234
}

رسم الخرائط

فبدون تخطيط متغير، وسلسلة من أعلى المستويات، ورقم، وميادين فوليان في خريطة الحمولة إلى متغيرات تدفق العمل من نفس الاسم آليا؛ وتُستثنى الأجسام المصنوعة والصفائف من المسح التلقائي.

لإعادة تسميتها variableMapping : المفتاح هو الاسم المتغير لتدفق العمل، القيمة هي الاسم الميداني للحمولة من أعلى المستويات. فالميادين العليا هي الوحيدة التي تحظى بالدعم؛ وليست هناك مستلزمات للبحث عن الطرق.

# Webhook 配置
"variableMapping": { "branch": "ref", "repo_name": "repo" }

# 触发 payload
{ "ref": "refs/heads/main", "repo": "my-app" }

# 工作流实际拿到的输入
{ "branch": "refs/heads/main", "repo_name": "my-app" }

إذا كان الحقل المصنّع مفقوداً من الحمولة المتغيّر لا يُحقن، ولا تزال القيمة الافتراضية في نموذج سير العمل سارية (لن تكون مخطّطة بسلسلة فارغة).

التوقيعات على اتفاقية مكافحة الفساد (للإدماجات القديمة)

"ويهوك" بدون مفتاح "إم بي آي" لكن مع secretKey (أ) استخدام طريقة التركة الخاصة باتفاقية مكافحة الفساد: يجب أن يتضمن طلب بدء التشغيل توقيعاً في العنوان:

X-Webhook-Signature: sha256=<hex(HMAC-SHA256(rawRequestBody, secretKey))>

التوقيع = HmacSHA256(rawRequestBody, secretKey) ناتج كسلسلة هكسيّة، مع أو بدونها عودة خاطئة 401.

A webhook with an API Key bound no longer accepts HMAC signatures (even if the secretKey field still has a value); migrating to API Key is one-way. "ويب هوك" الذي ليس له طريقة في وقته لا يتأكد من هوية الزناد.

مسار الزناد الإرث POST /api/webhook-trigger/{webhookId} ولا يزال متاحاً بسلوك متطابق؛ واستخدام المسار الكانتوني أعلاه للتكاملات الجديدة.

الردود الخاطئة

سيناريوهات الوصول المشتركة

• GitHub push — خريطة اسم الفرع وإلزام صاحب البلاغ بالمتغيرات؛ وتدفق العمل يبني ويختبر وينشر تلقائياً
• CI 系统 — اكتمل البناء → يقوم Webhook بتشغيل مسار الإصدار اللاحق
• Lark / 飞书机器人 — تشغيل معالجة الدُفعات التشغيلية بعد تلقي أمر محدد
• IoT 上报 — إنذار الجهاز → يقوم Webhook بتشغيل استكشاف أخطاء سير العمل وإصلاحها وتجميع الإنذارات

نقاط نهاية الإدارة

القائمة GET /api/webhooksتحديث PUT /api/webhooks/{id}تحذف DELETE /api/webhooks/{id}زائد GET /api/webhooks/{id}/stats وتعود إلى ظهور الإحصائيات؛ وجميعها نقاط نهائية موثقة.

عند إعادة تشغيل الخدمة

تنفيذ مُتَعَوَّل بواسطة مُعادَة خدمةِ لَنْ يَكُونَ عِنْدَهُ عِنْدَهُ عَلَى التَحَمُّلُ، الحمولة تُعَالَج في النهاية، والمنبر لا يُعيدُ تشغيله. فالتنفيذات التي سبق أن تم وقفها في الروايات اليدوية هي الاستثناءات التي تستمر كالمعتاد بمجرد الموافقة عليها. ولإعادة التشغيل، يجب أن يُرسل النظام في أعلى المجرى طلب الزناد مرة أخرى (يؤدي ذلك إلى تنفيذ جديد).

الصفحات ذات الصلة

• نقطة نهاية منصة مفتوحة على شبكة ويهوك (الاسترجاع على أساس الموافقة)
• مفاتيح ونطاقات API