118 lines
5.2 KiB
Plaintext
118 lines
5.2 KiB
Plaintext
---
|
||
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).
|