واجهة برمجة خطافات الويب

إعداد خطافات ويب لكل نموذج وخطافات عامة لإشعارات الاستجابات في الوقت الفعلي.

تتيح لك خطافات الويب تلقي إشعارات HTTP POST في الوقت الفعلي عندما تستقبل النماذج إرسالات جديدة. يدعم NueForm مستويين من خطافات الويب:

خطافات ويب النموذج -- عنوان URL واحد لكل نموذج يستقبل الإرسالات لذلك النموذج المحدد.
خطافات ويب عامة -- حتى 5 عناوين URL تستقبل الإرسالات من جميع نماذجك.

تتطلب خطافات الويب خطة Pro أو أعلى. محاولة استخدام نقاط نهاية خطافات الويب على الخطة المجانية ستُرجع خطأ 403.

تستخدم جميع هياكل الطلبات والاستجابات أسماء حقول بتنسيق snake_case.

Endpoints

GET/api/v1/forms/:id/webhooksPUT/api/v1/forms/:id/webhooksGET/api/v1/webhooksPUT/api/v1/webhooksGET/api/v1/webhooks/secretPOST/api/v1/webhooks/secret

الحصول على خطاف ويب النموذج

GET/api/v1/forms/:id/webhooks

يسترجع عنوان URL لخطاف الويب المُعدّ لنموذج محدد.

معاملات المسار

idstringمطلوب

معرّف النموذج

إذا لم يكن هناك خطاف ويب مُعدّ، سيكون webhook_url بقيمة null.

الاستجابة

json

{
  "webhook_url": "https://example.com/hooks/nueform"
}

أمثلة الشيفرة البرمجية

bash

curl -X GET "https://api.nueform.io/api/v1/forms/665a1b2c3d4e5f6a7b8c9d0e/webhooks" \
  -H "Authorization: Bearer YOUR_API_KEY"

تعيين خطاف ويب النموذج

PUT/api/v1/forms/:id/webhooks

يُعيّن أو يمسح عنوان URL لخطاف الويب لنموذج محدد. عند استقبال إرسال، سيُرسل NueForm طلب HTTP POST إلى هذا العنوان مع بيانات الاستجابة.

معاملات المسار

idstringمطلوب

معرّف النموذج

جسم الطلب

urlstring or nullمطلوب

عنوان URL لخطاف الويب. يجب أن يكون عنوان URL صالحاً. عيّنه إلى null لإزالة خطاف الويب.

مثال الطلب

json

{
  "url": "https://example.com/hooks/nueform"
}

لإزالة خطاف الويب:

json

{
  "url": null
}

الاستجابة

json

{
  "webhook_url": "https://example.com/hooks/nueform"
}

أمثلة الشيفرة البرمجية

bash

curl -X PUT "https://api.nueform.io/api/v1/forms/665a1b2c3d4e5f6a7b8c9d0e/webhooks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com/hooks/nueform" }'

عرض خطافات الويب العامة

GET/api/v1/webhooks

يسترجع جميع خطافات الويب العامة المُعدّة لحسابك. تُطلَق خطافات الويب العامة لكل إرسال نموذج عبر جميع نماذجك.

الاستجابة

json

{
  "webhooks": [
    {
      "url": "https://example.com/hooks/all-forms",
      "enabled": true
    },
    {
      "url": "https://backup.example.com/hooks/nueform",
      "enabled": false
    }
  ]
}

أمثلة الشيفرة البرمجية

bash

curl -X GET "https://api.nueform.io/api/v1/webhooks" \
  -H "Authorization: Bearer YOUR_API_KEY"

تعيين خطافات الويب العامة

PUT/api/v1/webhooks

يستبدل جميع خطافات الويب العامة بالمصفوفة المُقدَّمة. يمكنك إعداد حتى 5 خطافات ويب عامة. يمكن تفعيل أو تعطيل كل خطاف ويب بشكل فردي.

جسم الطلب

webhooksarrayمطلوب

مصفوفة كائنات خطافات الويب (الحد الأقصى 5)

مثال الطلب

json

{
  "webhooks": [
    {
      "url": "https://example.com/hooks/all-forms",
      "enabled": true
    },
    {
      "url": "https://slack-webhook.example.com/nueform",
      "enabled": true
    },
    {
      "url": "https://backup.example.com/hooks/nueform",
      "enabled": false
    }
  ]
}

الاستجابة

json

{
  "webhooks": [
    {
      "url": "https://example.com/hooks/all-forms",
      "enabled": true
    },
    {
      "url": "https://slack-webhook.example.com/nueform",
      "enabled": true
    },
    {
      "url": "https://backup.example.com/hooks/nueform",
      "enabled": false
    }
  ]
}

أمثلة الشيفرة البرمجية

bash

curl -X PUT "https://api.nueform.io/api/v1/webhooks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "webhooks": [
      { "url": "https://example.com/hooks/all-forms", "enabled": true },
      { "url": "https://backup.example.com/hooks/nueform", "enabled": false }
    ]
  }'

الحصول على سر خطاف الويب

GET/api/v1/webhooks/secret

يسترجع سر توقيع خطاف الويب الخاص بك. إذا لم يكن هناك سر بعد، يتم توليد واحد تلقائياً. السر هو سلسلة سداسية عشرية مكونة من 64 حرفاً مشتقة من 32 بايت عشوائي.

استخدم هذا السر للتحقق من أن طلبات خطاف الويب الواردة هي فعلاً من NueForm عن طريق التحقق من صحة توقيع HMAC-SHA256 في رأس X-NueForm-Signature.

التحقق من التوقيعات

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

الاستجابة

json

{
  "secret": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2"
}

أمثلة التحقق من التوقيع

javascript

const crypto = require("crypto");

function verifyWebhookSignature(body, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(body)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

أمثلة الشيفرة البرمجية

bash

curl -X GET "https://api.nueform.io/api/v1/webhooks/secret" \
  -H "Authorization: Bearer YOUR_API_KEY"

إعادة توليد سر خطاف الويب

POST/api/v1/webhooks/secret

يُولّد سر توقيع جديد لخطاف الويب، ليحل محل السر الحالي. بعد إعادة التوليد، سيتم توقيع جميع عمليات تسليم خطافات الويب بالسر الجديد.

بعد إعادة التوليد، قم بتحديث مستقبلات خطافات الويب فوراً لاستخدام السر الجديد. ستفشل الطلبات الموقعة بالسر القديم في التحقق.

الاستجابة

json

{
  "secret": "f0e1d2c3b4a5968778695a4b3c2d1e0f9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d"
}

أمثلة الشيفرة البرمجية

bash

curl -X POST "https://api.nueform.io/api/v1/webhooks/secret" \
  -H "Authorization: Bearer YOUR_API_KEY"

تنسيق حمولة خطاف الويب

عندما يستقبل نموذج إرسالاً، يُرسل NueForm طلب POST إلى عناوين URL لخطافات الويب المُعدّة مع الحمولة التالية.

يُحدد حقل event نوع الحدث، ويحتوي كائن response على بيانات الإرسال الكاملة بما في ذلك جميع الإجابات.

الرؤوس

Content-Typeapplication/json

نوع محتوى جسم الطلب

X-NueForm-Signaturestring

ملخص HMAC-SHA256 السداسي العشري لجسم الطلب

X-NueForm-Eventstring

نوع الحدث (مثلاً، response.submitted)

مثال الحمولة

json

{
  "event": "response.submitted",
  "form_id": "665a1b2c3d4e5f6a7b8c9d0e",
  "form_title": "Customer Feedback Survey",
  "response": {
    "id": "667a1b2c3d4e5f6a7b8c9d01",
    "submitted_at": "2026-02-27T15:42:00.000Z",
    "completed_at": "2026-02-27T15:45:30.000Z",
    "answers": [
      {
        "question_id": "66a1b2c3d4e5f6a7b8c9d001",
        "question_title": "What is your name?",
        "value": "Jane Smith"
      }
    ]
  }
}

استجابات الأخطاء

استجابات الأخطاء القياسية التي تُرجعها نقاط نهاية خطافات الويب.

رموز الأخطاء

400Bad Request

تنسيق URL غير صالح، تجاوز الحد الأقصى 5 خطافات ويب عامة، أو حقول مطلوبة مفقودة

401Unauthorized

مفتاح API مفقود أو غير صالح

403Forbidden

تتطلب خطافات الويب خطة Pro أو أعلى

404Not Found

النموذج غير موجود

500Server Error

خطأ داخلي في الخادم

مثال خطأ

json

{
  "error": "Webhooks require a Pro plan or higher"
}

آخر تحديث: 6 أبريل 2026