إعداد خطافات الويب (webhooks) لأحداث الوكيل

يرسل خطاف الويب (webhook) طلب POST موقعاً إلى نقطة النهاية الخاصة بك في اللحظة التي يحدث فيها شيء ما، مثل انتهاء مهمة الوكيل أو انتظار الوكيل للموافقة، حتى لا تضطر أنظمتك إلى الاستقصاء. تغطي هذه المقالة إضافة نقطة نهاية، والأحداث، والحمولة، والتحقق من التوقيع، وما يحدث عند فشل عمليات التسليم.

قبل البدء#

• خطافات الويب (webhooks) متاحة في خطط Pro وBusiness وCustom ("خطافات الويب متاحة في خطة Pro وما فوق.").
• مالك مساحة العمل والمسؤولون فقط هم من يديرون خطافات الويب. يرى الأعضاء الآخرون "المالكون والمسؤولون فقط هم من يديرون خطافات الويب".
• تحتاج إلى عنوان https عام يستجيب بحالة 2xx في غضون 10 ثوانٍ.
• يمكن أن تحتوي مساحة العمل على ما يصل إلى 10 خطافات ويب.

إضافة خطاف ويب (webhook)#

1. افتح علامة تبويب خطافات الويب (Webhooks)#

   افتح قائمة مساحة العمل، واختر AI agents & API، ثم افتح Webhooks. انقر على خطاف ويب (webhook) جديد.

   

2. أدخل نقطة النهاية#

   • رابط نقطة النهاية (Endpoint URL): "عنوان HTTPS عام." على سبيل المثال https://example.com/clevera/webhooks.
   • الوصف: اختياري، يصل إلى 200 حرف، على سبيل المثال "ترحيل Slack".

3. اختر الأحداث#

   حدد الأحداث التي تريد تلقيها، أو جميع الأحداث، بما في ذلك الأحداث الجديدة. الأحداث المميزة بـ قريباً مقبولة ولكن "لا يوجد شيء يرسل هذا الحدث بعد."

   

4. أنشئه وقم بتخزين الرمز السري#

   انقر على إنشاء خطاف ويب. يظهر رمز التوقيع السري (يبدأ بـ whsec_) مرة واحدة: "انسخه الآن: لن تراه مرة أخرى. استخدمه للتحقق من ترويسة Clevera-Signature." قم بتخزينه مثل كلمة المرور، ثم انقر على لقد قمت بتخزينه.

5. إرسال حدث تجريبي#

   افتح قائمة ⋯ الخاصة بخطاف الويب واختر إرسال حدث تجريبي. ترسل Clevera حدث ping موقعاً مرة واحدة (بدون إعادة محاولات). تعني "تم إرسال الحدث التجريبي" أنه غادر Clevera؛ تحقق من عمليات التسليم لمعرفة رد نقطة النهاية الخاصة بك.

الأحداث#

هذه الأحداث مدرجة كـ قريباً ولم يتم إرسالها بعد: job.progress، video.ready، article.ready، research.completed، insights.weekly.

تغطي أحداث المهمة المهام التي يبدأها الوكلاء (من خلال رمز API أو تطبيق متصل)، وليس مقاطع الفيديو التي يبدأها الأشخاص في التطبيق.

ما ترسله Clevera#

كل عملية تسليم هي POST مع نص JSON وترويسات:

تحمل الحمولات معرفات، وروابط، وحالات، وأرقاماً، ولا تحمل المحتوى نفسه أبداً. لقراءة فيديو أو مقالة منتهية، اتصل بـ API باستخدام رمز.

{
  "id": "6f1c2d3e-4b5a-4c6d-8e9f-0a1b2c3d4e5f",
  "event": "job.succeeded",
  "created_at": "2026-10-20T14:03:11Z",
  "data": {
    "job": {
      "id": "job_8k2m4n6p8r0t2v4x",
      "kind": "video.create",
      "status": "succeeded",
      "error_code": null,
      "subject": { "type": "video", "id": "vid_example" },
      "credits_spent": 64
    },
    "needs_input": null,
    "workspace": { "id": "tm_example" }
  }
}

{
  "id": "0b9a8c7d-6e5f-4a3b-9c2d-1e0f9a8b7c6d",
  "event": "approval.requested",
  "created_at": "2026-10-20T14:01:02Z",
  "data": {
    "approval": {
      "id": "apr_example",
      "kind": "spend",
      "status": "pending",
      "credits_high": 80,
      "expires_at": "2026-10-21T14:01:02Z",
      "decided_at": null,
      "url": "https://app.clevera.ai/agents?tab=requests&team=tm_example"
    },
    "job": { "id": "job_8k2m4n6p8r0t2v4x", "kind": "video.create" },
    "workspace": { "id": "tm_example" }
  }
}

التحقق من التوقيع#

تحقق من كل عملية تسليم قبل الوثوق بها. التوقيع هو HMAC-SHA256، مشفر برمز التوقيع السري الخاص بك، للطابع الزمني، ونقطة، ونص الطلب الخام: <t>.<body>.

1. اقرأ t و v1 من ترويسة Clevera-Signature.
2. احسب HMAC-SHA256(secret, t + "." + rawBody) كـ hex.
3. قارنه بـ v1 في وقت ثابت.
4. ارفض عمليات التسليم التي يكون t الخاص بها قديماً لأكثر من 5 دقائق، حتى لا يمكن إعادة تشغيل طلب تم التقاطه.

import crypto from 'node:crypto';

export function verifyClevera(rawBody, header, secret, toleranceSeconds = 300) {
  const parts = Object.fromEntries(header.split(',').map((p) => p.trim().split('=')));
  const t = Number(parts.t);
  if (!parts.v1 || !Number.isInteger(t)) return false;
  if (Math.abs(Date.now() / 1000 - t) > toleranceSeconds) return false;
  const expected = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
  return expected.length === parts.v1.length &&
    crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}

import hashlib, hmac, time

def verify_clevera(raw_body: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
    parts = dict(p.strip().split("=", 1) for p in header.split(","))
    t, v1 = parts.get("t", ""), parts.get("v1", "")
    if not t.isdigit() or not v1 or abs(time.time() - int(t)) > tolerance:
        return False
    expected = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, v1)

function verifyClevera(string $rawBody, string $header, string $secret, int $tolerance = 300): bool
{
    parse_str(str_replace(',', '&', $header), $parts);
    $t = $parts['t'] ?? '';
    $v1 = $parts['v1'] ?? '';
    if (! ctype_digit($t) || $v1 === '' || abs(time() - (int) $t) > $tolerance) {
        return false;
    }
    return hash_equals(hash_hmac('sha256', $t.'.'.$rawBody, $secret), $v1);
}

استخدم النص كما تم استلامه تماماً. تحليل وإعادة ترميز JSON أولاً يغير البايتات ولن يتطابق التوقيع.

إعادة المحاولات والإخفاقات#

تُحتسب عملية التسليم كـ "تم التسليم" عندما تستجيب نقطة النهاية الخاصة بك بحالة 2xx. أي شيء آخر يفشل في المحاولة:

• أي حالة أخرى، بما في ذلك عمليات إعادة التوجيه (لا يتم اتباع 3xx)؛
• عدم وجود إجابة في غضون 10 ثوانٍ (5 ثوانٍ للاتصال)؛
• عنوان لم يعد يحل إلى الإنترنت العام.

تعيد Clevera محاولة التسليم الفاشل 5 مرات، بعد دقيقة واحدة، و5 دقائق، و30 دقيقة، وساعتين، و6 ساعات. لا تتم قراءة نص استجابة نقطة النهاية الخاصة بك أبداً.

عندما تفشل 15 عملية تسليم متتالية في كل محاولة، يتم إيقاف خطاف الويب: "تم الإيقاف بعد 15 عملية تسليم فاشلة متتالية. أصلح نقطة النهاية، ثم قم بتشغيله." يتلقى المالك والمسؤولون إشعاراً بـ "تم إيقاف خطاف الويب الخاص بـ host": "استمرت عمليات تسليمه في الفشل. أصلح نقطة النهاية، ثم قم بتشغيله مرة أخرى." الأحداث التي تحدث أثناء إيقافه لا يتم إرسالها. لا تُحتسب الأحداث التجريبية ضمن هذا.

إدارة خطاف ويب (webhook)#

انقر على عمليات التسليم في خطاف ويب لرؤية سجله، أو افتح قائمة ⋯ الخاصة به للبقية:

إذا غادرت مساحة العمل خطة Pro#

تظل خطافات الويب مدرجة ويمكن تعديلها وحذفها، ولكن لا يتم إرسال أي شيء. تنتهي عمليات التسليم التي تنتظر إعادة المحاولة كفاشلة مع plan_locked، ويقول إرسال حدث تجريبي وإعادة التسليم "خطافات الويب ليست ضمن خطتك." تؤدي الترقية مرة أخرى إلى Pro إلى بدء الإرسال مرة أخرى؛ لا يتم حذف أي شيء.

استكشاف الأخطاء وإصلاحها#

ذات صلة#