HTTP Webhook

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

متى تستخدمها

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

التهيئة

1. في محرّر النموذج، هيّئ عقدة Start بمستقبِل Webhook وارد.
2. يولّد betool عنوان URL عامًّا (https://platform.betool.ai/entries/webhook/<token>).
3. (مُوصى به) عرِّف سرّ HMAC في تهيئة المستقبِل.

عند تهيئة سرّ، يجب على نظامك توقيع الجسم الخام لكل طلب — HMAC-SHA256(secret, body)، بالنظام الست عشري — وتمرير التوقيع في ترويسة X-Webhook-Signature، بالشكل sha256=<hex> أو <hex> وحده. اسم الترويسة والخوارزمية (sha256، sha384، sha512) قابلان للتهيئة، مثلًا لمطابقة اصطلاح X-Hub-Signature-256 الخاص بـGitHub. وعندها يُرفَض أي طلب بلا توقيع صالح (401).

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

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

يُقرأ الجسم بحسب Content-Type الخاص به: JSON مُحلَّل، والنموذج (application/x-www-form-urlencoded) كقاموس، وXML وtext/* كنصّ خام، وmultipart/form-data كحقول + ملفات مرفقة (webhook.payload._files)، وأي نوع آخر (PDF، صورة، أرشيف…) يُحفَظ كملف. ويُفكّ ضغط الجسم المضغوط بـgzip. الحجم الأقصى: 50 MB (413 بعد ذلك).

مثال:

curl -X POST https://platform.betool.ai/entries/webhook/abc123 \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Signature: sha256=$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 مباشرةً.

الاستجابة

وضعان للاستجابة (response_mode): sync (الافتراضي) يُحجَب حتى نتيجة الـpipeline ويُعيدها في الاستجابة؛ و**ack** يُعيد فورًا 202 Accepted بعد وضع الحدث في طابور متين (يُنفَّذ الـpipeline بعد ذلك، مع إعادة المحاولة) — وهو الخيار المناسب للمزوّدين الذين تنتهي مهلتهم مبكرًا.

طلبات GET (خيار)

افتراضيًا، لا يُقبَل إلا POST: ويتلقّى GET الرمز 405. ولشريك يفرض الاستعلام عبر GET ?action=…، فعِّل قبول GET أيضًا (allow_get). تصبح سلسلة الاستعلام عندئذٍ webhook.payload، بالشكل نفسه لـPOST من نموذج: لا يحتاج الـpipeline إلى معرفة الطريقة المستخدَمة. لا يحمل GET أي body (يُرفَض بـ400) ولا يتوافق مع توقيع HMAC (يُرفَض بـ405 ما دام هناك سرّ مُعرَّف). يظهر المعرّف المُمرَّر في الاستعلام في سجلّات الوصول: فضِّل POST عندما يسمح الشريك بذلك.

الأمان

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