خطافات الويب

يقوم Twenty بإرسال طلب HTTP POST إلى URL الخاص بك كلما تم إنشاء سجل أو تحديثه أو حذفه. جميع أنواع الكائنات مشمولة، بما في ذلك الكائنات المخصصة.

إنشاء خطاف ويب

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

يتم تفعيل خطاف الويب فورًا ويبدأ في إرسال الإشعارات.

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

تحرير: انقر على خطاف الويب → تحديث عنوان 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"
}

الحقل	الوصف
`event`	ما الذي حدث (على سبيل المثال، `person.created`)
`data`	السجل الكامل الذي تم إنشاؤه/تحديثه/حذفه
`timestamp`	وقت حدوث الحدث (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 receivedSignature = req.headers["x-twenty-webhook-signature"];
const isValid = crypto.timingSafeEqual(
  Buffer.from(expectedSignature, "hex"),
  Buffer.from(receivedSignature, "hex")
);