نظرة عامة على Webhooks

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

كيف تعمل Webhooks

عندما يُرسل المستجيب نموذجاً، يقوم NueForm فوراً بإرسال طلب HTTP من نوع POST إلى كل عنوان URL لـ webhook قمت بإعداده. يحتوي جسم الطلب على حمولة JSON موقّعة تتضمن نوع الحدث وتفاصيل النموذج والإجابات المُرسلة.

تسير العملية على النحو التالي:

1. يُكمل المستجيب النموذج ويُرسله.
2. يتحقق NueForm من صحة الإجابات ويحفظ الاستجابة.
3. يُنشئ NueForm حمولة JSON تحتوي على بيانات الحدث.
4. يوقّع NueForm الحمولة بمفتاح webhook السري الخاص بك باستخدام HMAC-SHA256.
5. يُرسل NueForm الحمولة كطلب POST إلى كل عنوان URL مُعدّ.
6. يستقبل خادمك الطلب، ويتحقق من التوقيع، ويعالج البيانات.

تسليم Webhook يعمل بأسلوب أطلق وانسَ وهو غير حاجب. لا تؤثر حالات فشل webhook أبداً على تدفق الإرسال --- يرى المستجيبون دائماً إرسالاً ناجحاً بغض النظر عن إمكانية الوصول إلى نقطة نهاية webhook الخاصة بك.

Webhooks لكل نموذج مقابل Webhooks العامة

يدعم NueForm نوعين من إعدادات webhook:

Webhooks لكل نموذج

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

يمكنك تعيين عنوان URL لـ webhook لكل نموذج من خلال:

• لوحة تحكم NueForm --- افتح إعدادات النموذج وأدخل عنوان URL لـ webhook.
• واجهة API --- استخدم واجهة Webhooks API لتعيين أو تحديث العنوان برمجياً.

curl -X PUT https://app.nueform.com/api/v1/webhooks/form/FORM_ID \
  -H "Authorization: Bearer nf_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://your-server.com/webhooks/nueform" }'

Webhooks العامة

تُفعّل Webhooks العامة لـ جميع النماذج في حسابك. وهي مفيدة للتسجيل المركزي والتحليلات أو تكاملات CRM التي تحتاج إلى معالجة جميع الإرسالات بغض النظر عن النموذج الذي جاءت منه.

يمكنك إعداد ما يصل إلى ٥ webhooks عامة، ويمكن تفعيل أو تعطيل كل منها بشكل فردي.

curl -X PUT https://app.nueform.com/api/v1/webhooks/global \
  -H "Authorization: Bearer nf_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "webhooks": [
      { "url": "https://analytics.example.com/nueform", "enabled": true },
      { "url": "https://crm.example.com/inbound", "enabled": true },
      { "url": "https://staging.example.com/test", "enabled": false }
    ]
  }'

ترتيب التسليم

عند إرسال نموذج، يُرسل NueForm الـ webhooks إلى جميع العناوين المعنية بالتوازي:

1. عنوان URL لـ webhook الخاص بالنموذج (إن كان مُعيّناً).
2. جميع عناوين URL لـ webhooks العامة المُفعّلة.

يستقبل كل هدف نفس الحمولة بنفس التوقيع.

متى تُفعّل Webhooks

حالياً، تُفعّل webhooks عند حدث واحد:

للنماذج التي تم تفعيل الإرسال التدريجي فيها، يُفعّل webhook فقط عندما تُعلّم الاستجابة كمكتملة --- لا تُفعّل عمليات الحفظ الجزئي webhooks.

راجع الأحداث للاطلاع على مرجع الأحداث الكامل والأحداث المستقبلية المخطط لها.

أمان Webhook

يتضمن كل طلب webhook ترويسة X-NueForm-Signature تحتوي على ملخص HMAC-SHA256 بصيغة سداسية عشرية لجسم الطلب. يجب عليك دائماً التحقق من هذا التوقيع قبل معالجة بيانات webhook للتأكد من أن الطلب صادر فعلاً من NueForm.

يتم إنشاء مفتاح webhook السري تلقائياً في أول مرة تصل إليه، ويمكن إعادة إنشائه في أي وقت عبر واجهة API أو لوحة التحكم.

راجع التحقق لتفاصيل التنفيذ ونماذج الأكواد.

خصائص التسليم

البداية السريعة

لبدء استقبال webhooks:

1. احصل على مفتاح webhook السري --- استدعِ GET /api/v1/webhooks/secret أو ابحث عنه في لوحة التحكم ضمن إعدادات المطوّر. ينشئ NueForm مفتاحاً سرياً تلقائياً إن لم يكن لديك واحد.
2. أعدّ عنوان URL لـ webhook --- قم بإعداد عنوان URL لكل نموذج أو أضف webhook عام.
3. نفّذ نقطة النهاية --- أنشئ نقطة نهاية HTTP تقبل طلبات POST، وتتحقق من التوقيع، وتعالج الحمولة.
4. اختبرها --- استخدم أداة مثل webhook.site أو ngrok للتحقق من التسليم قبل الانتقال إلى الإنتاج. راجع اختبار Webhooks لتعليمات مفصلة.

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

• الأحداث --- تعرّف على أنواع أحداث webhook
• الحمولات --- اطلع على مخطط الحمولة الكامل والأمثلة
• التحقق --- نفّذ التحقق من توقيع HMAC-SHA256
• الاختبار --- اختبر webhooks أثناء التطوير المحلي