upstream-twenty/packages/twenty-docs/l/ar/developers/extend/webhooks.mdx

---
title: خطافات الويب
icon: satellite-dish
description: احصل على إشعار عند تغيّر السجلات — سيتم إرسال طلب HTTP POST إلى endpoint الخاص بك عند كل عملية إنشاء أو تحديث أو حذف.
---

import { VimeoEmbed } from '/snippets/vimeo-embed.mdx';

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

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

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

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

<VimeoEmbed videoId="928786708" title="إنشاء خطاف ويب" />

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

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

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

## الأحداث

يرسل Twenty خطافات الويب لأنواع الأحداث التالية:

| حدث             | مثال                                                       |
| --------------- | ---------------------------------------------------------- |
| **إنشاء سجل**   | `person.created`, `company.created`, `note.created`        |
| **تحديث السجل** | `person.updated`, `company.updated`, `opportunity.updated` |
| **حذف السجل**   | `person.deleted`, `company.deleted`                        |

يتم إرسال جميع أنواع الأحداث إلى عنوان URL لخطاف الويب الخاص بك. قد تتم إضافة تصفية الأحداث في الإصدارات المستقبلية.

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

يرسل كل خطاف ويب طلب HTTP من نوع POST يتضمن جسمًا بصيغة JSON:

```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)                            |

<Note>
استجب بحالة **HTTP 2xx** ‏(200-299) لتأكيد الاستلام. تُسجَّل الاستجابات غير 2xx كإخفاقات في التسليم.
</Note>

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

يقوم 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)

```javascript
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")
);
```

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

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

لاستقبال البيانات الخارجية، راجع [إعداد مشغّل خطاف الويب](/l/ar/user-guide/workflows/how-tos/connect-to-other-tools/set-up-a-webhook-trigger).