أحداث Webhook

يُرسل NueForm إشعارات webhook لأحداث محددة تحدث في حسابك. يتضمن كل طلب webhook حقل event في حمولة JSON يُحدد ما حدث.

الأحداث الحالية

form.submitted

يُفعّل عندما يُرسل المستجيب استجابة كاملة لأحد نماذجك.

هذا هو حدث webhook الرئيسي في NueForm. يُفعّل لكل من النماذج القياسية (إرسال واحد) ونماذج الإرسال التدريجي، لكن فقط عندما تصل الاستجابة إلى حالة مكتملة.

متى يُفعّل:

• في النموذج القياسي: فوراً بعد أن ينقر المستجيب على إرسال وتُحفظ الاستجابة.
• في النموذج التدريجي: فقط عندما يُرسل الإرسال النهائي مع complete: true. لا تُفعّل عمليات الحفظ الجزئي هذا الحدث.
• في نماذج وضع الاختبار (اختبار المعرفة، تأهيل العملاء المحتملين، اختبار المطابقة): تتضمن الحمولة نتائج تسجيل الاختبار إلى جانب الإجابات.

متى لا يُفعّل:

• الإرسالات الجزئية في النماذج التدريجية (حيث complete ليس true).
• تعديلات الاستجابات الموجودة (الاستجابات غير قابلة للتغيير بعد الإرسال).
• مسودات النماذج أو المعاينات.
• إرسالات الاختبار من معاينة مُنشئ النماذج.

راجع الحمولات لمخطط الحمولة الكامل.

الأحداث المستقبلية المخطط لها

الأحداث التالية مخطط لها في الإصدارات المستقبلية. لم تتوفر بعد لكنها موثقة هنا لتتمكن من تصميم تكاملك مع مراعاة التوافق المستقبلي.

form.partial

سيُفعّل عندما تُحفظ استجابة جزئية في نموذج مع تفعيل الإرسال التدريجي. سيتيح لك تتبع التخلي عن النماذج والمتابعة مع المستجيبين الذين بدأوا لكن لم يُكملوا.

form.completed

سيُفعّل عندما تنتقل استجابة تدريجية من جزئية إلى مكتملة. يختلف هذا عن form.submitted في أنه يشير صراحة إلى أن استجابة جزئية سابقة قد أُنهيت.

form.published

سيُفعّل عندما يُنشر نموذج أو يُعاد نشره.

form.unpublished

سيُفعّل عندما يُلغى نشر نموذج (يُؤخذ دون اتصال).

ضمانات تسليم الأحداث

فهم كيفية تسليم NueForm لأحداث webhook مهم لبناء تكاملات موثوقة.

التسليم لمرة واحدة على الأكثر

يوفر NueForm حالياً دلالات تسليم لمرة واحدة على الأكثر. يُرسل كل حدث مرة واحدة ولا يُعاد إرساله إذا فشل التسليم. هذا يعني:

• قد تفوت نقطة النهاية أحداثاً أحياناً إذا كانت غير متاحة مؤقتاً.
• لن تتلقى أبداً أحداثاً مكررة لنفس الإرسال من نظام تسليم NueForm.
• يجب أن تصمم تكاملك ليتحمل الأحداث المفقودة.

لا إعادة محاولة تلقائية

إذا كانت نقطة النهاية غير قابلة للوصول، أو أعادت رمز حالة خطأ، أو لم تستجب خلال نافذة المهلة الزمنية البالغة ٥ ثوانٍ، يتم إسقاط تسليم webhook بصمت. لا يقوم NueForm بتخزين أو إعادة محاولة التسليمات الفاشلة.

الترتيب

تُرسل أحداث webhook بالترتيب الذي تحدث فيه، لكن نظراً لإرسالها إلى عناوين URL متعددة بالتوازي واختلاف ظروف الشبكة، ترتيب التسليم غير مضمون. إذا تطلب تطبيقك ترتيباً صارماً، استخدم طابع وقت submittedAt في الحمولة لترتيب الأحداث بعد الاستلام.

المهلة الزمنية

ينتظر NueForm ما يصل إلى ٥ ثوانٍ لاستجابة نقطة النهاية. إذا لم تستجب نقطة النهاية خلال هذه النافذة، يتم إلغاء الطلب. يجب أن تستجب نقطة النهاية برمز حالة 2xx بأسرع ما يمكن وتؤجل أي معالجة ثقيلة إلى مهمة خلفية.

تجنب التكرار

على الرغم من أن NueForm لا يُرسل أحداثاً مكررة بالتصميم، قد تتسبب ظروف الشبكة (مثل إعادة إرسال TCP) نظرياً في استقبال نقطة النهاية لنفس الحمولة أكثر من مرة. استخدم حقل responseId في الحمولة كمفتاح تجنب تكرار لإزالة التكرار بأمان.

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

1. استجب بسرعة. أعد 200 OK فوراً وعالج بيانات webhook بشكل غير متزامن. لدى NueForm مهلة زمنية ٥ ثوانٍ.

2. تحقق من التوقيعات. تحقق دائماً من ترويسة X-NueForm-Signature قبل الوثوق بالحمولة. راجع التحقق.

3. استخدم مفاتيح تجنب التكرار. خزّن قيم responseId المعالجة وتخطَّ التكرارات.

4. طابق دورياً. كمّل webhooks الفورية بالاستعلام المجدول لواجهة الاستجابات API لالتقاط أي أحداث مفقودة.

5. راقب نقطة النهاية. تتبع أوقات الاستجابة ومعدلات الأخطاء في نقطة نهاية webhook. إذا فشلت نقطة النهاية باستمرار، فكر في تنفيذ قائمة انتظار (مثل SQS أو Redis) بين مستقبل webhook ومنطق المعالجة.

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

• الحمولات --- اطلع على مخطط حمولة JSON الكامل
• التحقق --- نفّذ التحقق من التوقيع
• الاختبار --- اختبر تسليم webhook محلياً