كتلة استجابة الويب هوك - إرسال استجابات HTTP مخصصة لمتصلي الويب هوك

نظرة عامة

تتيح لك كتلة استجابة الويب هوك إرسال استجابة HTTP مخصصة إلى أي نظام استدعى كتلة الويب هوك الخاصة بك. بدون هذه الكتلة، يرد ChatMaxima بـ 200 OK عام ونص {"status":"success"}. هذا جيد لمعظم الاستدعاءات، لكن بعض التكاملات تتوقع شكلاً أو رمز حالة أو نوع محتوى محدداً قبل أن تعتبر التسليم ناجحاً.

استخدم كتلة استجابة الويب هوك عندما يكون المتصل صارماً بشأن الرد: بوابات الدفع التي تعيد المحاولة ما لم تشاهد حقل JSON معيناً، أو أنظمة SOAP القديمة التي تتوقع XML، أو أدوات iPaaS التي تحلّل الاستجابة إلى خطوات لاحقة، أو منشئي النماذج الذين يعرضون الرد للمستخدم.

كتلة الويب هوك مقابل كتلة استجابة الويب هوك

الجانب	كتلة الويب هوك	كتلة استجابة الويب هوك
الاتجاه	يستقبل استدعاء HTTP وارداً	يرسل استجابة HTTP إلى المتصل
الموضع	الكتلة الأولى أو في منتصف التدفق	في أي مكان بعد كتلة الويب هوك
مطلوب	نعم (لقبول الاستدعاءات الخارجية)	اختياري (يُرسل 200 OK افتراضي إذا حُذف)
الغرض	تشغيل التدفق أو استئنافه	تشكيل رد HTTP للمتصل

أين تجدها

1. افتح روبوت المحادثة الخاص بك في Studio
2. اسحب كتلة استجابة الويب هوك من الشريط الجانبي الأيسر إلى اللوحة
3. اربطها بعد كتلة الويب هوك التي استقبلت الطلب
4. انقر نقراً مزدوجاً على الكتلة لتهيئتها

لا تحتاج كتلة استجابة الويب هوك إلى أن تكون الكتلة التالية مباشرةً. يمكنك وضع كتل الشرط وAPI وضبط المتغير والرسالة بين كتلة الويب هوك وكتلة استجابة الويب هوك. عند الوصول إلى كتلة الاستجابة أثناء تنفيذ التدفق، تصبح تهيئتها رد HTTP للمتصل الأصلي.

التهيئة

الخطوة 1: ضبط رمز حالة HTTP

رمز الحالة	استخدمه عندما
200	الافتراضي. يشير إلى النجاح لمعظم المتصلين
201	مفيد عندما أنشأ الويب هوك مورداً (مثل محادثة جديدة)
202	مقبول للمعالجة غير المتزامنة (سيتصرّف الروبوت بناءً عليه لاحقاً)
400	رفض الحمولات المشوّهة
401	رفض المتصلين غير المصرّح لهم
500	الإشارة إلى فشل على جانب الروبوت لمنطق إعادة المحاولة

الخطوة 2: ضبط Content-Type

Content-Type	استخدمه عندما
application/json	معظم التكاملات الحديثة (الافتراضي)
application/xml	متصلو SOAP القديمون
text/plain	استدعاءات بنمط فحص الصحة
text/html	إقرارات إرسال النماذج المعروضة للمستخدم

الخطوة 3: كتابة محتوى الاستجابة

المحتوى حقل نصي حر. اكتب الحمولة الدقيقة التي تريد إعادتها إلى المتصل. يمكن إدراج المتغيرات الملتقطة سابقاً في التدفق بصيغة {variable_name} (قوسان معقوفان مفردان).

لـ JSON:

{
  "received": true,
  "conversation_id": "{conversation_id}",
  "lead_id": "{reference_id}",
  "acknowledged_at": "{current_time}"
}

لـ XML:

<response>
  <status>success</status>
  <conversation_id>{conversation_id}</conversation_id>
</response>

لنص عادي:

OK

الخطوة 4: الإرسال والحفظ

انقر على إرسال في نافذة الكتلة، ثم احفظ التدفق باستخدام حفظ التغييرات في الشريط العلوي.

كيف تعمل

External system POSTs to webhook URL
                 │
                 ▼
       Webhook Block fires
                 │
                 ▼
   (Optional) intermediate blocks:
   - Condition to validate payload
   - API Block to enrich data
   - Set Variable to compute fields
                 │
                 ▼
    Webhook Response Block reached
                 │
                 ▼
    Custom HTTP response returned
    to the original caller
                 │
                 ▼
    Flow continues to downstream blocks
    (messages, further logic, etc.)

تُرسل استجابة HTTP بشكل متزامن: يبقى المتصل الخارجي متصلاً حتى الوصول إلى كتلة الاستجابة. لهذا السبب، أبقِ المسار بين كتلة الويب هوك وكتلة استجابة الويب هوك سريعاً. تجنّب استدعاءات API طويلة الأمد أو المنطق المستهلك للوقت قبل كتلة الاستجابة، وإلا فقد تنتهي مهلة المتصل.

حالات الاستخدام الشائعة

الإقرار بمعرّف المحادثة

تريد أداة iPaaS (n8n أو Zapier أو Make) تسجيل معرّف المحادثة في نظامها الخاص بعد تشغيل الويب هوك.

• رمز الحالة: 201
• Content-Type: application/json
• النص:

{
  "created": true,
  "conversation_id": "{conversation_id}",
  "reference_id": "{reference_id}"
}

إعادة نتيجة التحقق

يرسل منشئ نماذج إدخال المستخدم. يتحقق الروبوت منه ويعيد نجاح/فشل بحيث يمكن للنموذج عرض الرسالة الصحيحة.

• رمز الحالة: 200
• Content-Type: application/json
• النص:

{
  "valid": true,
  "message": "Your request has been received"
}

رفض الحمولات غير الصالحة

اجمع كتلة شرط (تتحقق من الحقول المطلوبة) مع كتلة استجابة ويب هوك على فرع الفشل تعيد 400.

• رمز الحالة: 400
• Content-Type: application/json
• النص:

{
  "error": "missing_required_field",
  "field": "{missing_field}"
}

تأكيد بوابة الدفع

ترسل بوابة دفع ويب هوك settle. على الروبوت إعادة شكل JSON محدد وإلا ستستمر البوابة في إعادة المحاولة.

• رمز الحالة: 200
• Content-Type: application/json
• النص:

{
  "status": "acknowledged",
  "transaction_id": "{transaction_id}"
}

إيصال تسليم الرسائل النصية القصيرة

يتوقع مزود رسائل نصية قديم استجابة نص عادي OK.

• رمز الحالة: 200
• Content-Type: text/plain
• النص: OK

أفضل الممارسات

• أبقِ المسار قصيراً. ضع الكتل بين الويب هوك واستجابة الويب هوك فقط إذا كانت تعمل بسرعة. يجب أن تذهب استدعاءات API الطويلة بعد كتلة الاستجابة بحيث لا تنتهي مهلة المتصل
• أعد دائماً بسرعة للمتصلين الذين يعيدون المحاولة. غالباً ما تعيد بوابات الدفع ومزودو الرسائل النصية المحاولة خلال ثوانٍ. الوصول إلى كتلة الاستجابة خلال ثانية أو ثانيتين يتجنّب الإشعارات المكررة
• طابق الشكل المتوقع للمتصل بالضبط. يرفض المتصلون الصارمون الاستجابات حتى عندما يكون رمز الحالة صحيحاً. اقرأ وثائق التكامل واختبر بطلباتهم النموذجية
• استخدم كتل الشرط لتفرّع الاستجابة. اجعل كتلة استجابة ويب هوك واحدة على فرع النجاح وأخرى مختلفة (بـ 400 أو 401) على فرع الفشل
• ضمّن معرّف المحادثة أو المرجع. يسهّل هذا ربط سجلات المتصل بالمحادثة في ChatMaxima
• لا تضع بيانات حساسة في الاستجابة. الاستجابة مرئية للمتصل. أعد فقط ما يحتاجه لتأكيد الاستلام

استكشاف الأخطاء وإصلاحها

يستقبل المتصل 200 OK الافتراضي بدلاً من استجابتي المخصصة

1. تأكد من وجود كتلة استجابة ويب هوك ويمكن الوصول إليها من كتلة الويب هوك
2. تحقق من مخطط التدفق: إذا وجّه شرط حول كتلة الاستجابة، يُستخدم الافتراضي
3. تأكد من حفظ الكتلة. انقر على إرسال في النافذة، ثم حفظ التغييرات في الشريط العلوي

المتصل يعيد المحاولة بشكل متكرر

1. تأكد من أن رمز الحالة يطابق ما يعتبره المتصل نجاحاً. يقبل بعض المزودين 200 فقط، وليس 201 أو 202
2. تحقق من أن محتوى الاستجابة يطابق الشكل المتوقع للمتصل. افحص وثائقهم أو سجلاتهم
3. تحقق من الكتل العلوية بين الويب هوك واستجابة الويب هوك التي تكون بطيئة. قد ينتهي مهلة المتصل قبل إرسال الاستجابة

تظهر المتغيرات كـ {variable_name} خام في محتوى الاستجابة

1. تأكد من ضبط المتغير بواسطة كتلة سابقة في التدفق نفسه
2. أسماء المتغيرات حساسة لحالة الأحرف. تحقق من التهجئة
3. للحقول المتداخلة، استخدم العلامة النقطية: {customer.email}، وليس {customer_email}
4. إذا كان المتغير من حمولة الويب هوك الواردة، تأكد من أن الحمولة احتوت فعلياً على الحقل

رفض المتصلون الصارمون JSON المشوّه

1. تحقق من صحة قالب النص كـ JSON قبل الحفظ. سيُنتج متغير غير مقتبس في حقل سلسلة JSON غير صالحاً إذا احتوت القيمة على علامات اقتباس أو فواصل أسطر
2. للحقول الرقمية مثل {amount}، لا تضعها بين علامات اقتباس. للحقول النصية، ضعها دائماً بين علامات اقتباس: "name": "{name}"
3. اختبر باستدعاء نموذجي (باستخدام curl أو Postman) لرؤية البايتات الفعلية المعادة

عدم تطابق Content-Type

1. يتطلب بعض المتصلين application/json; charset=utf-8 صراحةً. يرسل الافتراضي application/json بدون مجموعة الأحرف
2. قد يتطلب عملاء SOAP text/xml بدلاً من application/xml. راجع وثائق التكامل

الخطوات التالية

• كتلة الويب هوك - استقبال استدعاءات HTTP واردة لتشغيل تدفق أو استئنافه
• كتلة API - استدعاء واجهات برمجة التطبيقات الخارجية من التدفق
• نظرة عامة على Studio - استكشف جميع أنواع الكتل وميزات مُنشئ التدفق