يتطلب اختبار webhooks أثناء التطوير أن تكون نقطة النهاية قابلة للوصول من الإنترنت العام. يغطي هذا الدليل عدة طرق، من أدوات الفحص السريع إلى إعدادات التطوير المحلي الكاملة.
الخيار ١: webhook.site (فحص سريع)
يوفر webhook.site عنوان URL عاماً مؤقتاً يلتقط ويعرض طلبات HTTP الواردة. هذه أسرع طريقة لرؤية ما يُرسله NueForm دون كتابة أي كود.
- اذهب إلى webhook.site.
- انسخ العنوان الفريد (مثل
https://webhook.site/abc123-def456-...). - عيّنه كعنوان URL لـ webhook الخاص بنموذجك:
curl -X PUT https://app.nueform.com/api/v1/webhooks/form/YOUR_FORM_ID \
-H "Authorization: Bearer nf_your_api_key" \
-H "Content-Type: application/json" \
-d '{ "url": "https://webhook.site/abc123-def456-..." }'
- أرسل استجابة لنموذجك.
- حدّث webhook.site لرؤية الطلب الملتقط، بما في ذلك الترويسات والجسم و
X-NueForm-Signature.
webhook.site ممتاز للفحص لكنه لا يتيح تشغيل منطق تحقق مخصص. استخدمه لفهم تنسيق الحمولة، ثم انتقل إلى خادم محلي للاختبار الكامل.
الخيار ٢: ngrok (التطوير المحلي)
يُنشئ ngrok نفقاً آمناً من عنوان URL عام إلى جهازك المحلي. هذا يتيح لك استقبال تسليمات webhook حقيقية على خادم التطوير.
الإعداد
- ثبّت ngrok:
# macOS (Homebrew)
brew install ngrok
# أو حمّل من https://ngrok.com/download
- شغّل خادم webhook المحلي (مثلاً، على المنفذ 3001):
node server.js
# أو
python app.py
- شغّل نفق ngrok:
ngrok http 3001
- انسخ عنوان HTTPS للتوجيه من مخرجات ngrok:
Forwarding https://a1b2c3d4.ngrok-free.app -> http://localhost:3001
- عيّن عنوان ngrok كنقطة نهاية webhook:
curl -X PUT https://app.nueform.com/api/v1/webhooks/form/YOUR_FORM_ID \
-H "Authorization: Bearer nf_your_api_key" \
-H "Content-Type: application/json" \
-d '{ "url": "https://a1b2c3d4.ngrok-free.app/webhooks/nueform" }'
- أرسل استجابة لنموذجك. سيصل webhook إلى خادمك المحلي.
فحص حركة المرور
يوفر ngrok واجهة ويب محلية على http://localhost:4040 حيث يمكنك فحص جميع الطلبات المارة عبر النفق وإعادة تشغيلها وعرض الترويسات ورموز الاستجابة.
تتغير عناوين ngrok المجانية في كل مرة تعيد تشغيل ngrok. تذكر تحديث عنوان URL لـ webhook في NueForm عند الحصول على عنوان نفق جديد. فكر في الترقية إلى خطة ngrok مدفوعة للحصول على نطاق فرعي ثابت.
الخيار ٣: curl (محاكاة الحمولات)
يمكنك استخدام curl لإرسال حمولات webhook تجريبية إلى خادمك المحلي دون المرور عبر NueForm على الإطلاق. هذا مفيد لاختبار منطق التحقق والمعالجة بشكل منفصل.
إنشاء حمولة اختبار موقّعة
أولاً، أنشئ حمولة اختبار ووقّعها بمفتاح webhook السري:
# مفتاح webhook السري (من واجهة NueForm API أو لوحة التحكم)
SECRET="a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2"
# حمولة الاختبار
PAYLOAD='{
"event": "form.submitted",
"formId": "507f1f77bcf86cd799439011",
"formTitle": "Test Form",
"responseId": "507f1f77bcf86cd799439022",
"answers": [
{ "questionId": "507f1f77bcf86cd799439033", "value": "Test answer" },
{ "questionId": "507f1f77bcf86cd799439044", "value": 5 }
],
"submittedAt": "2025-03-15T14:32:07.123Z"
}'
# حساب توقيع HMAC-SHA256
SIGNATURE=$(echo -n "$PAYLOAD" | openssl dgst -sha256 -hmac "$SECRET" | awk '{print $2}')
echo "Signature: $SIGNATURE"
إرسال الطلب الموقّع
curl -X POST http://localhost:3001/webhooks/nueform \
-H "Content-Type: application/json" \
-H "X-NueForm-Signature: $SIGNATURE" \
-d "$PAYLOAD"
سطر واحد
ادمج كل شيء في أمر واحد:
SECRET="your_secret_here"
PAYLOAD='{"event":"form.submitted","formId":"507f1f77bcf86cd799439011","formTitle":"Test Form","responseId":"507f1f77bcf86cd799439022","answers":[{"questionId":"q1","value":"hello"}],"submittedAt":"2025-03-15T14:32:07.123Z"}'
SIGNATURE=$(echo -n "$PAYLOAD" | openssl dgst -sha256 -hmac "$SECRET" | awk '{print $2}')
curl -X POST http://localhost:3001/webhooks/nueform \
-H "Content-Type: application/json" \
-H "X-NueForm-Signature: $SIGNATURE" \
-d "$PAYLOAD"
اختبار رفض التوقيع
للتحقق من أن نقطة النهاية ترفض التوقيعات غير الصالحة بشكل صحيح، أرسل طلباً بتوقيع خاطئ:
curl -X POST http://localhost:3001/webhooks/nueform \
-H "Content-Type: application/json" \
-H "X-NueForm-Signature: 0000000000000000000000000000000000000000000000000000000000000000" \
-d '{"event":"form.submitted","formId":"test","formTitle":"Test","responseId":"test","answers":[],"submittedAt":"2025-03-15T14:32:07.123Z"}'
يجب أن تعيد نقطة النهاية 401 Unauthorized.
الخيار ٤: سكريبت Node.js للاختبار
أنشئ سكريبت Node.js مستقل لتوقيع وإرسال حمولات اختبار بسرعة:
import crypto from 'crypto';
const SECRET = process.env.NUEFORM_WEBHOOK_SECRET || 'your_secret_here';
const ENDPOINT = process.env.WEBHOOK_URL || 'http://localhost:3001/webhooks/nueform';
const payload = JSON.stringify({
event: 'form.submitted',
formId: '507f1f77bcf86cd799439011',
formTitle: 'Customer Feedback Survey',
responseId: crypto.randomUUID().replace(/-/g, '').slice(0, 24),
answers: [
{ questionId: 'q_name', value: 'Jane Doe' },
{ questionId: 'q_email', value: 'jane@example.com' },
{ questionId: 'q_rating', value: 4 },
{ questionId: 'q_feedback', value: 'Great product!' },
{ questionId: 'q_features', value: ['Feature A', 'Feature C'] },
],
submittedAt: new Date().toISOString(),
});
const signature = crypto
.createHmac('sha256', SECRET)
.update(payload)
.digest('hex');
const response = await fetch(ENDPOINT, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-NueForm-Signature': signature,
},
body: payload,
});
console.log(`Status: ${response.status}`);
console.log(`Body: ${await response.text()}`);
شغّله بـ:
NUEFORM_WEBHOOK_SECRET=your_secret node test-webhook.mjs
الخيار ٥: تفعيل إرسال حقيقي
الطريقة الأكثر شمولاً للاختبار هي إرسال استجابة فعلية لنموذجك:
- أعدّ عنوان URL لـ webhook (لكل نموذج أو عام) ليشير إلى نقطة نهاية الاختبار.
- افتح نموذجك المنشور في المتصفح.
- أكمل النموذج وأرسله.
- راقب تسليم webhook على نقطة النهاية.
هذا يختبر خط الأنابيب بالكامل من البداية إلى النهاية، بما في ذلك التحقق من الإجابات وتسجيل الاختبار والحمولة الفعلية التي يُنشئها NueForm.
تصحيح أخطاء التسليمات الفاشلة
إذا كانت نقطة نهاية webhook لا تستقبل الطلبات، راجع قائمة التحقق هذه:
١. تحقق من إعداد العنوان
# تحقق من webhook الخاص بالنموذج
curl https://app.nueform.com/api/v1/webhooks/form/YOUR_FORM_ID \
-H "Authorization: Bearer nf_your_api_key"
# تحقق من webhooks العامة
curl https://app.nueform.com/api/v1/webhooks/global \
-H "Authorization: Bearer nf_your_api_key"
٢. تحقق من إمكانية الوصول للعنوان
# اختبر أن نقطة النهاية تقبل طلبات POST
curl -X POST https://your-endpoint.com/webhooks/nueform \
-H "Content-Type: application/json" \
-d '{"test": true}'
٣. تحقق من وجود مفتاح webhook سري
لا تُرسل Webhooks إلا إذا كان لحسابك مفتاح webhook سري مُعيّن. تحقق:
curl https://app.nueform.com/api/v1/webhooks/secret \
-H "Authorization: Bearer nf_your_api_key"
إذا أظهرت الاستجابة مفتاحاً سرياً، فأنت جاهز. إذا لم يكن كذلك، سيتم إنشاء واحد تلقائياً بهذا الطلب.
٤. تحقق من خطتك
تتطلب Webhooks خطة Pro أو أعلى. تحقق من حالة خطتك في لوحة تحكم NueForm ضمن إعدادات حسابك.
٥. تحقق من المهلة الزمنية
لدى NueForm مهلة زمنية ٥ ثوانٍ. إذا استغرقت نقطة النهاية وقتاً أطول للاستجابة، سيتم إلغاء الطلب. تأكد من إعادة 200 OK فوراً ومعالجة البيانات في الخلفية.
٦. تحقق من قواعد الجدار الناري والشبكة
تأكد من أن خادمك يسمح بطلبات POST الواردة من مصادر خارجية. إذا كنت خلف جدار ناري أو VPN، قد تحتاج إلى إضافة نطاقات IP الخاصة بـ NueForm إلى القائمة المسموحة أو استخدام ngrok.
أخطاء الاختبار الشائعة
| الخطأ | الحل |
|---|---|
استخدام وسيط express.json() قبل التحقق من التوقيع | استخدم express.raw({ type: 'application/json' }) على مسار webhook |
| الاختبار بمفتاح API ملغى أو منتهي الصلاحية | أنشئ مفتاح API جديداً |
| نسيان تفعيل webhooks العامة | عيّن "enabled": true على كل إدخال webhook عام |
| استخدام HTTP بدلاً من HTTPS لعنوان webhook | يُرسل NueForm إلى أي عنوان URL تقدمه، لكن استخدم HTTPS في الإنتاج |
| عدم التحقق من وجود مفتاح webhook سري | تأكد من وجود مفتاح webhook سري في حسابك قبل توقع التسليمات |