الانتقال إلى المحتوى الرئيسي
تدفع خطافات الويب البيانات إلى أنظمتك في الوقت الفعلي عند وقوع أحداث في Twenty — دون الحاجة إلى الاستطلاع الدوري. استخدمها للحفاظ على تزامن الأنظمة الخارجية، وتشغيل الأتمتة، أو إرسال التنبيهات.

إنشاء ربط ويب

  1. انتقل إلى الإعدادات → APIs & Webhooks → Webhooks
  2. انقر على + إنشاء ربط ويب
  3. أدخل عنوان URL لخطاف الويب الخاص بك (يجب أن يكون قابلاً للوصول علنًا)
  4. انقر على حفظ
يتم تفعيل خطاف الويب فورًا ويبدأ في إرسال الإشعارات.

إدارة Webhooks

تحرير: انقر على خطاف الويب → تحديث عنوان URL → حفظ حذف: انقر على خطاف الويب → حذف → تأكيد

الأحداث

يرسل Twenty خطافات الويب لأنواع الأحداث التالية:
حدثمثال
إنشاء سجلperson.created, company.created, note.created
تحديث السجلperson.updated, company.updated, opportunity.updated
حذف السجلperson.deleted, company.deleted
يتم إرسال جميع أنواع الأحداث إلى عنوان URL لخطاف الويب الخاص بك. قد تتم إضافة تصفية الأحداث في الإصدارات المستقبلية.

تنسيق الحمولة

يرسل كل خطاف ويب طلب HTTP من نوع POST يتضمن جسمًا بصيغة JSON:
{
  "event": "person.created",
  "data": {
    "id": "abc12345",
    "firstName": "Alice",
    "lastName": "Doe",
    "email": "alice@example.com",
    "createdAt": "2025-02-10T15:30:45Z",
    "createdBy": "user_123"
  },
  "timestamp": "2025-02-10T15:30:50Z"
}
الحقلالوصف
حدثما الذي حدث (على سبيل المثال، person.created)
بياناتالسجل الكامل الذي تم إنشاؤه/تحديثه/حذفه
الطابع الزمنيوقت حدوث الحدث (UTC)
استجب بحالة HTTP 2xx ‏(200-299) لتأكيد الاستلام. تُسجَّل الاستجابات غير 2xx كإخفاقات في التسليم.

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

يقوم Twenty بتوقيع كل طلب خطاف ويب لأغراض الأمان. تحقّق من التواقيع للتأكد من أن الطلبات أصيلة.

الرؤوس

رأس الصفحةالوصف
X-Twenty-Webhook-Signatureتوقيع HMAC SHA256
X-Twenty-Webhook-Timestampالطابع الزمني للطلب

خطوات التحقق

  1. احصل على الطابع الزمني من X-Twenty-Webhook-Timestamp
  2. أنشئ السلسلة: {timestamp}:{JSON payload}
  3. احسب HMAC SHA256 باستخدام سر خطاف الويب الخاص بك
  4. قارِن مع X-Twenty-Webhook-Signature

مثال (Node.js)

const crypto = require("crypto");

const timestamp = req.headers["x-twenty-webhook-timestamp"];
const payload = JSON.stringify(req.body);
const secret = "your-webhook-secret";

const stringToSign = `${timestamp}:${payload}`;
const expectedSignature = crypto
  .createHmac("sha256", secret)
  .update(stringToSign)
  .digest("hex");

const isValid = expectedSignature === req.headers["x-twenty-webhook-signature"];

خطافات الويب مقابل سير العمل

طريقةالاتجاهحالة الاستخدام
خطافات الويبOUTإخطار الأنظمة الخارجية تلقائيًا بأي تغيير في السجل
سير العمل + طلب HTTPOUTإرسال البيانات إلى الخارج بمنطق مخصص (عوامل تصفية، تحويلات)
مشغّل خطاف ويب لسير العملINاستقبال البيانات في Twenty من الأنظمة الخارجية
لاستقبال البيانات الخارجية، راجع إعداد مشغّل خطاف الويب.