نظرة عامة على 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.io/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.io/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 السري للحساب الذي يملك النموذج. لا تحتاج إلى إنشائه مسبقًا: إن لم يكن لديك مفتاح بعد، ينشئه NueForm عندما تفتح علامة التبويب المطور في الملف الشخصي، أو عندما تستدعي GET /api/v1/webhooks/secret، أو عند أول تسليم لأحد نماذجك. ويمكنك إعادة إنشائه في أي وقت من علامة التبويب نفسها أو عبر POST /api/v1/webhooks/secret.

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

المفاتيح السرية لنماذج الفرق

تُوقَّع تسليمات نموذج الفريق بالمفتاح السري لمالك الفريق، لذا تحقّق منها بهذا المفتاح. لا ينشئ NueForm هذا المفتاح من تلقاء نفسه: إلى أن يمتلك مالك الفريق مفتاحًا سريًا، تُتخطّى تسليمات نماذج الفريق — فلا يُرسل شيء ولا تُسجَّل أي محاولة فاشلة. ينشئه مالك الفريق بفتح علامة التبويب المطور في ملفه الشخصي مرة واحدة، أو باستدعاء GET /api/v1/webhooks/secret بمفتاح API الخاص به. أما الاستدعاء نفسه بمفتاح 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 أثناء التطوير المحلي