betool betool

الوثائق

webhooks الصادرة

أشعِر أنظمتك الخارجية بأحداث betool — فشل التنفيذ، الرصيد المنخفض، الحاجة إلى تحقّق بشري.

webhooks الصادرة

في حين تستقبل قناة webhook الواردة أحداثًا خارجية لمعالجتها، تقوم webhooks الصادرة بالعكس: فهي تُشعِر أنظمتك عند وقوع حدث جدير بالملاحظة في betool.

لماذا

من المرجّح أنّ لديك فعلًا:

  • نظام تنبيهات (PagerDuty، Opsgenie، Slack).
  • أداة ITSM (Jira، ServiceNow) لإدارة التذاكر.
  • لوحة معلومات مخصّصة تجمّع حالتك التشغيلية.

بدلًا من مطالبة هذه الأنظمة باستطلاع واجهة betool باستمرار، اشترِكها في webhooks الصادرة: يجري إشعارها فورًا عند حدوث أمرٍ ما.

التهيئة

  1. الإدارة ← webhooks الصادرة ← اشتراك جديد.
  2. اختَر:
    • عنوان URL الهدف — نقطة النهاية التي ستستقبل طلبات POST.
    • الأحداث المراد الإصغاء إليها — راجع القائمة أدناه.
    • سرّ HMAC — يُنشأ تلقائيًّا؛ استخدمه في جانب المُستقبِل للتحقّق من التوقيعات.
  3. (اختياري) عوامل التصفية — الاقتصار على عمليات تنفيذ pipeline معيّن، أو على مستوى خطورة معيّن، إلخ.

الأحداث المتاحة

الحدثمتى يُطلَق
execution.failedفشل تنفيذ pipeline
execution.requires_humanعقدة confirmation تنتظر تحقّقًا
execution.cost_thresholdتجاوز تنفيذٌ عتبة تكلفة
billing.low_balanceانخفض رصيد الاعتمادات دون العتبة المهيّأة
billing.out_of_creditsالرصيد صفر (رفض ما قبل الاستدعاء مُفعَّل)
audit.cross_tenant_readقرأ agent خارجي محتوى من هذه المؤسسة
webhook.delivery_failedفشل webhook صادر سابق 3 مرات

صيغة POST

POST /your/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": "support email triage",
    "failed_node": "agent: classifier",
    "error_kind": "llm_timeout",
    "error_message": "Provider responded after 30s timeout"
  }
}

توقيع HMAC

تحتوي ترويسة 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)

إعادة المحاولة وعدم التكرار

  • إذا استجابت نقطة النهاية بـ 2xx، فإنّ الحدث يُوسَم على أنّه مُسلَّم.
  • إذا كانت الاستجابة خارج 2xx أو انتهت المهلة، تعيد betool المحاولة مع تراجع أسّي (دقيقة واحدة، 5 دقائق، 30 دقيقة، ساعتان، 12 ساعة، 24 ساعة — 6 محاولات كحدّ أقصى).
  • بعد 6 حالات فشل، يُوسَم الحدث على أنّه dead-letter ويُطلَق webhook.delivery_failed (إلى اشتراكاتك النشطة الأخرى).

يحمل كل طلب POST معرّف X-Betool-Delivery فريدًا. إذا استقبلت نقطة النهاية عملية التسليم نفسها مرتين (حالة حدّية للشبكة)، فعامِلها على أنّها غير قابلة للتكرار.

الأمن

  • HTTPS إلزامي — تُرفَض اشتراكات HTTP العادية.
  • سرّ قابل للتدوير — يمكنك إعادة توليد السرّ في أي وقت؛ وستظل طلبات POST الجارية التي تستخدم السرّ القديم مقبولة حتى انتهاء صلاحيتها (5 دقائق).
  • عناوين IP المصدر — تنشر betool عناوين IP الصادرة الخاصة بها على status.betool.fr كي تتمكّن من إدراجها في القائمة المسموح بها لدى جدارك الناري.