betool betool

الوثائق

HTTP Webhook

استقبال عام لأحداث HTTP موقَّعة من أي نظام.

HTTP Webhook

قناة webhook هي نقطة الدخول العامة لربط أي نظام قادر على إجراء HTTP POST. وهي الخيار الذي يجب اختياره عندما لا توجد قناة مخصّصة لمصدرك.

متى تستخدمها

  • ربط أداة داخلية (ERP، تطبيق أعمال، بوابة دفع).
  • استقبال أحداث من منصّة طرف ثالث تُتيح webhooks (Stripe، Shopify، SendGrid…).
  • تشغيل pipeline من مهمّة cron خارجية أو من CI pipeline.

التهيئة

  1. الإدارة ← Webhooks ← مدخل جديد.
  2. اختر الـpipeline المستهدَف.
  3. يولّد betool عنوان URL عامًّا (https://platform.betool.ai/entries/webhook/<id>) وسرّ HMAC.

يُستخدَم السرّ لتوقيع كل حمولة: يجب على نظامك حساب HMAC-SHA256(secret, body) وتمريره في ترويسة X-Betool-Signature. وتُرفَض الطلبات التي بلا توقيع صالح.

تنسيق الحمولة

أنت ترسل أي JSON تريده. ولا يقيّد betool البنية. وتُعرَض الحمولة على الـpipeline ضمن webhook.payload (مع مفاتيحها الفرعية).

مثال:

curl -X POST https://platform.betool.ai/entries/webhook/abc123 \
  -H "Content-Type: application/json" \
  -H "X-Betool-Signature: $SIGNATURE" \
  -d '{
    "type": "order.created",
    "order_id": "ord_42",
    "amount_cents": 9900,
    "customer_email": "client@exemple.com"
  }'

يمكن للـpipeline عندئذٍ ربط وكيل يقرأ webhook.payload.customer_email وwebhook.payload.amount_cents مباشرةً.

الاستجابة

افتراضيًا، تُعيد استجابة HTTP الرمز 202 Accepted فورًا (يُطلَق الـpipeline في الخلفية). وإذا احتجت إلى انتظار نتيجة الـpipeline، فهيّئ الـwebhook في وضع متزامن — يُحجَب الطلب حتى يكتمل الـpipeline (بمهلة 30 ثانية).

الأمان

  • وقّع طلباتك دائمًا (HMAC).
  • يمكن إعادة توليد السرّ من لوحة الإدارة (التدوير).
  • تُخزَّن الحمولات كنصّ صِرف في سجلّ التنفيذ — لا ترسل بيانات يجب تشفيرها أثناء النقل فقط.