Webhooks יוצאים

בעוד שערוץ webhook נכנס מקבל אירועים חיצוניים לעיבוד, webhooks יוצאים עושים את ההיפך: הם מתריעים למערכות שלכם כאשר מתרחש אירוע בולט ב-betool.

מדוע

כנראה שכבר יש לכם:

• מערכת alerting (PagerDuty, Opsgenie, Slack).
• כלי ITSM (Jira, ServiceNow) לניהול כרטיסים.
• dashboard מותאם המרכז את המצב התפעולי שלכם.

במקום לבקש ממערכות אלה לבצע polling ל-API של betool, הירשמו אותן ל-webhooks יוצאים: הן יקבלו התראה מיידית בכל אירוע.

הגדרה

1. ניהול → Webhooks יוצאים → מינוי חדש.
2. בחרו:
   • URL יעד — ה-endpoint שיקבל את ה-POSTs.
   • אירועים להאזנה — ראו רשימה להלן.
   • סוד HMAC — נוצר אוטומטית, לשימוש בצד המקבל שלכם לאימות חתימות.
3. (אופציונלי) פילטרים — הגבלה להרצות של פייפליין ספציפי, לרמת חומרה מסוימת וכו'.

אירועים זמינים

פורמט POST

POST /votre/endpoint HTTP/1.1
Content-Type: application/json
X-Betool-Event: execution.failed
X-Betool-Signature: sha256=...
X-Betool-Delivery: dlv_01HXYZ...

{
  "event": "execution.failed",
  "delivered_at": "2026-05-24T10:42:13Z",
  "org_id": "org_...",
  "data": {
    "execution_id": "exec_...",
    "pipeline_id": "pip_...",
    "pipeline_name": "tri d'emails support",
    "failed_node": "agent: classifier",
    "error_kind": "llm_timeout",
    "error_message": "Provider responded after 30s timeout"
  }
}

חתימת HMAC

ה-header‏ X-Betool-Signature מכיל sha256=<hmac> כאשר hmac = HMAC-SHA256(secret, body). אמתו אותו בקבלה כדי לוודא שהבקשה אכן מגיעה מ-betool:

import hmac, hashlib

def verify(body: bytes, signature: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(
        secret.encode(),
        body,
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

Retry ואידמפוטנטיות

• אם ה-endpoint שלכם מגיב 2xx, האירוע מסומן כנמסר.
• אם non-2xx או timeout, betool מנסה שוב עם exponential backoff (דקה, 5 דקות, 30 דקות, 2 שעות, 12 שעות, 24 שעות — 6 ניסיונות לכל היותר).
• לאחר 6 כשלונות, האירוע מסומן dead-letter ו-webhook.delivery_failed נשלח (למינויים הפעילים האחרים שלכם).

כל POST נושא מזהה ייחודי X-Betool-Delivery. אם ה-endpoint שלכם מקבל את אותה delivery פעמיים (מקרה רשת), טפלו בה כאידמפוטנטית.

אבטחה

• HTTPS חובה — מינויי HTTP פשוט נדחים.
• סוד ניתן לרוטציה — ניתן לחדש את הסוד בכל עת; POSTs שכבר בדרך ישתמשו בסוד הישן עד לפקיעתו (5 דקות).
• IP מקור — betool מפרסמת את כתובות ה-IP היוצאות שלה ב-status.betool.fr כדי לאפשר לכם להרשות אותן בחומת האש.