הגדרת Webhooks עבור אירועי סוכן

‏Webhook שולח POST חתום לכתובת היעד שלך ברגע שמשהו קורה, כמו סיום עבודה של סוכן או סוכן שממתין לאישור, כך שהמערכות שלך לא צריכות לבצע סקר (polling). מאמר זה מכסה הוספת כתובת יעד, את האירועים, ה-Payload, אימות החתימה ומה קורה כאשר משלוחים נכשלים.

לפני שמתחילים#

• Webhooks זמינים בתוכניות Pro, Business ו-Custom ("Webhooks זמינים ב-Pro ומעלה.").
• רק בעל סביבת העבודה ומנהלי מערכת יכולים לנהל Webhooks. חברים אחרים יראו "רק בעלים ומנהלים יכולים לנהל Webhooks".
• דרושה לך כתובת https ציבורית שמשיבה עם סטטוס 2xx תוך 10 שניות.
• סביבת עבודה יכולה להכיל עד 10 Webhooks.

הוספת Webhook#

1. פתיחת לשונית Webhooks#

   פתח את תפריט סביבת העבודה, בחר ב-AI agents & API, ולאחר מכן פתח את Webhooks. לחץ על Webhook חדש.

   

2. הזנת כתובת היעד#

   • Endpoint URL: "כתובת HTTPS ציבורית." לדוגמה https://example.com/clevera/webhooks.
   • תיאור: אופציונלי, עד 200 תווים, לדוגמה "Slack relay".

3. בחירת האירועים#

   סמן את האירועים לקבלה, או בחר ב-כל האירועים, כולל חדשים. אירועים המסומנים כ-בקרוב מתקבלים אך "שום דבר לא שולח את האירוע הזה עדיין."

   

4. יצירה ושמירת המפתח הסודי#

   לחץ על צור Webhook. ה-Signing secret (מתחיל ב-whsec_) מוצג פעם אחת: "העתק אותו עכשיו: לא תראה אותו שוב. השתמש בו כדי לבדוק את כותרת ה-Clevera-Signature." שמור אותו כמו סיסמה, ולאחר מכן לחץ על שמרתי את זה.

5. שליחת אירוע בדיקה#

   פתח את תפריט ה-⋯ של ה-Webhook ובחר ב-שלח אירוע בדיקה. Clevera שולחת אירוע ping חתום פעם אחת (ללא ניסיונות חוזרים). "אירוע בדיקה נשלח" אומר שהוא יצא מ-Clevera; בדוק את משלוחים עבור התשובה של כתובת היעד שלך.

אירועים#

אירועים אלו רשומים כ-בקרוב וטרם נשלחים: job.progress, video.ready, article.ready, research.completed, insights.weekly.

אירועי עבודה מכסים עבודות שסוכנים מתחילים (דרך אסימון API או אפליקציה מחוברת), לא סרטונים שאנשים מתחילים באפליקציה.

מה Clevera שולחת#

כל משלוח הוא POST עם גוף JSON וכותרות אלו:

נתוני ה-Payload נושאים מזהים, קישורים, סטטוסים ומספרים, לעולם לא את התוכן עצמו. כדי לקרוא סרטון או מאמר שהסתיים, קרא ל-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 משלוחים ברצף נכשלים בכל ניסיון, ה-Webhook כבה: "כבה לאחר 15 משלוחים שנכשלו ברצף. תקן את כתובת היעד, ואז הפעל אותו." הבעלים ומנהלי המערכת מקבלים התראה "Webhook ל-host כבה": "המשלוחים שלו המשיכו להיכשל. תקן את כתובת היעד, ואז הפעל אותו מחדש." אירועים שקורים בזמן שהוא כבוי לא נשלחים. אירועי בדיקה לא נספרים בזה.

ניהול Webhook#

לחץ על משלוחים ב-Webhook כדי לראות את הלוג שלו, או פתח את תפריט ה-⋯ שלו עבור השאר:

אם סביבת העבודה עוזבת את Pro#

Webhooks נשארים ברשימה ועדיין ניתן לערוך ולמחוק אותם, אך שום דבר לא נשלח. משלוחים שממתינים לניסיון חוזר מסתיימים כנכשלו עם plan_locked, ו-שלח אירוע בדיקה ו-שלח מחדש מציגים "Webhooks אינם בתוכנית שלך." שדרוג חזרה ל-Pro מתחיל לשלוח שוב; שום דבר לא נמחק.

פתרון בעיות#

קשור#