تدفع خطافات الويب البيانات إلى أنظمتك في الوقت الفعلي عند وقوع أحداث في Twenty — دون الحاجة إلى الاستطلاع الدوري. استخدمها للحفاظ على تزامن الأنظمة الخارجية، وتشغيل الأتمتة، أو إرسال التنبيهات.
إنشاء ربط ويب
- انتقل إلى الإعدادات → APIs & Webhooks → Webhooks
- انقر على + إنشاء ربط ويب
- أدخل عنوان URL لخطاف الويب الخاص بك (يجب أن يكون قابلاً للوصول علنًا)
- انقر على حفظ
يتم تفعيل خطاف الويب فورًا ويبدأ في إرسال الإشعارات.
إدارة 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 | الطابع الزمني للطلب |
خطوات التحقق
- احصل على الطابع الزمني من
X-Twenty-Webhook-Timestamp
- أنشئ السلسلة:
{timestamp}:{JSON payload}
- احسب HMAC SHA256 باستخدام سر خطاف الويب الخاص بك
- قارِن مع
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 | إخطار الأنظمة الخارجية تلقائيًا بأي تغيير في السجل |
| سير العمل + طلب HTTP | OUT | إرسال البيانات إلى الخارج بمنطق مخصص (عوامل تصفية، تحويلات) |
| مشغّل خطاف ويب لسير العمل | IN | استقبال البيانات في Twenty من الأنظمة الخارجية |
لاستقبال البيانات الخارجية، راجع إعداد مشغّل خطاف الويب.