الانتقال إلى المحتوى الرئيسي
Header

​
نظرة عامة

Webhooks in Twenty complement the API by enabling real-time notifications to your own applications when certain events happen in your CRM. Instead of continuously polling the API for changes, you can set up webhooks to have Twenty push data to your system whenever specific events occur (for example, when a new record is created or an existing record is updated). يساعد هذا في الحفاظ على تزامن الأنظمة الخارجية مع Twenty بشكل فوري وفعال. مع الويب هوك، سترسل Twenty طلب HTTP POST إلى عنوان URL تحدده، يحتوي على تفاصيل حول الحدث. You can then handle that data in your application (e.g., to update your external database, trigger workflows, or send alerts).

​
Setting Up a Webhook

To create a webhook in Twenty, use the APIs & Webhooks settings in your Twenty app:
  1. Navigate to Settings: In your Twenty application, go to Settings → APIs & Webhooks.
  2. Create a Webhook: Under Webhooks click on + Create webhook.
  3. أدخل عنوان URL: قدم عنوان نقطة النهاية على الخادم الخاص بك حيث ترغب في إرسال طلبات الويب هوك من Twenty. يجب أن يكون هذا عنوان URL قابل للوصول بشكل عام يمكنه معالجة طلبات POST.
  4. احفظ: انقر على احفظ لإنشاء الويب هوك. سيكون الويب هوك الجديد نشطاً فوراً.
You can create multiple webhooks if you need to send different events to different endpoints. Each webhook is essentially a subscription for all relevant events (at this time, Twenty sends all event types to the given URL; filtering specific event types may be configurable in the UI). إذا كنت بحاجة في أي وقت لإزالة ويب هوك، يمكنك حذفه من صفحة الإعدادات نفسها (اختر الويب هوك واختر الحذف).

​
Events and Payloads

Once a webhook is set up, Twenty will send an HTTP POST request to your specified URL whenever a trigger event occurs in your CRM data. تشمل الأحداث الشائعة التي تحفز الويب هوك ما يلي:
  • تم إنشاء سجل: على سبيل المثال، تم إضافة شخص جديد (person.created)، تم إنشاء شركة جديدة (company.created)، تم إنشاء ملاحظة (note.created)، إلخ.
  • تم تحديث سجل: على سبيل المثال، تم تحديث معلومات شخص موجود (person.updated)، تم تحرير سجل شركة (company.updated)، إلخ.
  • تم حذف سجل: على سبيل المثال، تم حذف شخص أو شركة (person.deleted, company.deleted).
  • أحداث أخرى: إذا كانت ذات صلة، أحداث الكائنات الأخرى أو المحفزات المخصصة (على سبيل المثال، إذا تم تحديث المهام أو الكائنات الأخرى، سيتم استخدام أنواع أحداث مماثلة مثل task.created, note.updated, إلخ.).
يحتوي طلب الويب هوك 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" تحتوي على تفاصيل السجل الجديد (نفس المعلومات التي ستحصل عليها إذا طلبت ذلك الشخص عبر الـ API).
  • "timestamp" هو وقت حدوث الحدث (بالتوقيت العالمي).
يجب أن يكون مستقبلك مستعدًا لاستقبال مثل هذه البيانات بتنسيق JSON عن طريق POST. عادةً، ستقوم بتحليل الـ JSON، والنظر إلى نوع "event" لفهم ما حدث، ثم استخدام "data" بناءً عليه (على سبيل المثال، إنشاء جهة اتصال جديدة في النظام الخاص بك، أو تحديث جهة اتصال موجودة). ملاحظة: من المهم الرد بحالة HTTP 2xx من نقطة نهاية الويب هوك الخاصة بك للاعتراف بالاستقبال الناجح. إذا لم يتلق مرسل الويب هوك من Twenty استجابة 2xx، فقد يعتبر التسليم فاشلاً. (في المستقبل، قد تحاول منطق إعادة المحاولة إعادة إرسال الويب هوكات الفاشلة، لذا حاول دائمًا إرجاع 200 OK في أسرع وقت ممكن بعد معالجة البيانات).

​
Webhook Validation

To ensure the security of your webhook endpoints, Twenty includes a signature in the X-Twenty-Webhook-Signature header. هذا التوقيع هو تجزئة HMAC SHA256 لحمل الطلب، محوسبة باستخدام سر الويب هوك الخاص بك. للتحقق من صحة التوقيع، ستحتاج إلى:
  1. دمج الطابع الزمني (من رأس X-Twenty-Webhook-Timestamp) مع نقطتين وسلسلة JSON من الحمولة
  2. حساب تجزئة HMAC SHA256 باستخدام سر الويب هوك الخاص بك كمفتاح ()
  3. مقارنة الناتج السداسي بنصيحة التوقيع
هنا مثال في Node.js: 
const crypto = require("crypto");
const timestamp = "1735066639761";
const payload = JSON.stringify({...});
const secret = "your-secret";
const stringToSign = `${timestamp}:${JSON.stringify(payload)}`;
const signature = crypto.createHmac("sha256", secret)
  .update(stringToSign)
  .digest("hex");