ضبط المسارات
عيّن الإعدادات ضمنplugins.entries.webhooks.config:
يقبل
secret سلسلة نصية عادية أو SecretRef: { source: "env" | "file" | "exec", provider: "default", id: "..." }.
يُسجَّل كل مسار مضبوط عند بدء التشغيل بغض النظر عما إذا كان سرّه قابلًا للحل
حاليًا. لا يؤدي تعذّر حل السر إلى تعطيل المسار أو تخطيه؛ إذ تفشل مصادقة
الطلبات إليه (401) إلى أن يصبح حل السر ممكنًا. يُعاد حل قيم SecretRef مع كل
طلب، لذا يسري تدوير السر الأساسي (متغير بيئة أو ملف أو مخرجات تنفيذ) من دون
إعادة تشغيل Gateway.
نموذج الأمان
يعمل كل مسار بصلاحيات TaskFlow الخاصة بـsessionKey المضبوط له: ويمكنه فحص
أي TaskFlow تملكها تلك الجلسة وتعديلها. يمر الوصول إلى TaskFlow دائمًا عبر
api.runtime.tasks.managedFlows.bindSession(...)، لذلك لا يمكن للمسار مطلقًا
العمل خارج جلسته المرتبطة. للحد من نطاق الضرر:
- استخدم سرًا قويًا وفريدًا لكل مسار.
- فضّل SecretRef على سر نصي صريح مضمن.
- اربط المسارات بأضيق جلسة تلائم سير العمل.
- اكشف فقط مسار Webhook المحدد الذي تحتاج إليه.
POST فقط) ومن
Content-Type: application/json، ثم تحديد المعدل بنافذة ثابتة (120 طلبًا لكل
نافذة مدتها 60 ثانية لكل مفتاح مؤلف من المسار وعنوان IP للعميل، مع تتبع ما يصل
إلى 4,096 مفتاحًا)، ثم تحديد الطلبات قيد التنفيذ (8 طلبات متزامنة لكل مفتاح،
مع تتبع ما يصل إلى 4,096 مفتاحًا)، ثم المصادقة بالسر المشترك، ثم قراءة نص JSON
بحد أقصى 256 كيلوبايت وخلال 15 ثانية. الطلبات التي تفشل في تحقق مبكر لا تصل
مطلقًا إلى عمليات التحقق اللاحقة.
تنسيق الطلب
أرسل طلباتPOST مع Content-Type: application/json وأحد الترويسَتين
Authorization: Bearer <secret> أو x-openclaw-webhook-secret: <secret>:
الإجراءات المدعومة
تتطلب إجراءات التعديل (
set_waiting وresume_flow وfinish_flow وfail_flow
وrequest_cancel) الحقلين flowId وexpectedRevision للتحكم المتفائل في
التزامن؛ وتعيد المراجعة القديمة 409 revision_conflict.
create_flow
run_task
قيم runtime المسموح بها: subagent وacp. لا تكون startedAt وlastEventAt
وprogressSummary صالحة إلا عندما تكون status هي "running"؛ ويؤدي إرسالها
مع أي حالة أخرى إلى إرجاع 400 invalid_request.
بنية الاستجابة
sessionKey المرتبط بالمسار. تتضمن قيم code:
not_found وnot_managed وrevision_conflict وpersist_failed
وcancel_requested وcancel_pending وterminal وinvalid_request
وrequest_rejected، بالإضافة إلى رموز احتياطية خاصة بالإجراء
(mutation_rejected وcreate_rejected وtask_not_created
وcancel_rejected) عندما يُرفض تعديل لسبب لا تغطيه الرموز المسماة أعلاه.
ذو صلة
- الخطافات - الخطافات الداخلية المستندة إلى الأحداث مقارنةً بجسر TaskFlow هذا المستند إلى HTTP
- Webhooks الخاصة بـ Gateway (إعداد
hooks.*) - ميزة منفصلة لنقطة نهاية HTTP عامة في Gateway؛ وليست مماثلة لمسارات هذه الإضافة - حزمة SDK لوقت تشغيل الإضافة
- Webhooks في CLI