كل ما يمكن عمله من شاشة الإعدادات > التكاملات > خطافات الويب يمكن عمله كذلك عبر واجهة التطبيق البرمجية، بحيث يستطيع التكامل تسجيل رابطه بنفسه دون فتح لوحة التحكم.
تتطلب جميع الطلبات رمز مِرسال، كما يحتاج صاحب الرمز إلى صلاحية الفريق المناسبة. راجع نظرة عامة على خطافات الويب لمتطلبات الخطة ودورة الحياة التي تديرها هذه النقاط.
{
"Accept": "application/json",
"Content-Type": "application/json",
"Authorization": "Bearer {مفتاحك هنا}"
}{
"id": 12,
"URL": "https://yourdomain.com/alaaqat-webhook",
"secret": "8f2c1d9b4a7e6035c1d8b2f4a9e7c603",
"is_validated": true,
"is_active": true,
"consecutive_failures": 0,
"last_failure_at": null,
"account_id": 1,
"created_at": "2026-08-27T10:15:00.000000Z",
"updated_at": "2026-08-27T10:22:31.000000Z",
"events": [
{
"id": 41,
"name": "contact-created",
"webhook_id": 12,
"created_at": "2026-08-27T10:15:00.000000Z",
"updated_at": "2026-08-27T10:15:00.000000Z"
}
]
}| الحقل | الوصف |
|---|---|
URL |
رابط HTTPS الخاص بك. |
secret |
المفتاح السري المكوّن من 32 خانة والمستخدم للرد على طلب التحقق. تُنشئه علاقات ولا يمكن تعيينه أو تغييره. |
is_validated |
ما إذا كان الرابط قد أجاب على طلب التحقق بشكل صحيح. |
is_active |
ما إذا كانت الإرسالات مفعّلة. لا تُرسل الأحداث إلا إذا كان is_validated و is_active كلاهما true. |
consecutive_failures |
عدد الإرسالات المتتالية التي استنفدت كل محاولاتها. أي إرسالة ناجحة تعيده إلى 0، وبلوغه 3 يوقف is_active. للقراءة فقط. |
last_failure_at |
وقت آخر إرسالة استنفدت محاولاتها، أو null إن لم يحدث ذلك قط. للقراءة فقط. |
events |
الأحداث المشترك بها هذا الخطاف. |
GET https://app.alaaqat.com/api/account/webhooks
تُرجع جميع خطافات الحساب الحالي. تتطلب صلاحية webhook-index.
{
"data": [
{
"id": 12,
"URL": "https://yourdomain.com/alaaqat-webhook",
"secret": "8f2c1d9b4a7e6035c1d8b2f4a9e7c603",
"is_validated": true,
"is_active": true,
"consecutive_failures": 0,
"last_failure_at": null,
"account_id": 1,
"created_at": "2026-08-27T10:15:00.000000Z",
"updated_at": "2026-08-27T10:22:31.000000Z",
"events": [
{
"id": 41,
"name": "contact-created",
"webhook_id": 12,
"created_at": "2026-08-27T10:15:00.000000Z",
"updated_at": "2026-08-27T10:15:00.000000Z"
}
]
}
]
}POST https://app.alaaqat.com/api/account/webhooks
تتطلب صلاحية webhook-create.
{
URL: string,
events: string[]
}| الحقل | مطلوب | التحقق | الوصف |
|---|---|---|---|
| URL | مطلوب | رابط صالح يستخدم https | الرابط الذي سيستقبل الإرسالات |
| events | مطلوب | مصفوفة تحتوي عنصراً واحداً على الأقل | الأحداث المراد الاشتراك بها |
| events.* | مطلوب | أحد الأحداث المتاحة | اسم الحدث، مثل contact-created |
تُرفض الحقول account_id و is_validated و is_active إن أُرسلت — فالخطاف الجديد يبدأ دائماً غير موثق وغير مفعّل، والمفتاح السري يُنشأ تلقائياً.
{
"URL": "https://yourdomain.com/alaaqat-webhook",
"events": ["contact-created", "contact-updated", "deal-created"]
}201 Created مع بيانات الخطاف الجديد بما فيها secret.
{
"data": {
"id": 12,
"URL": "https://yourdomain.com/alaaqat-webhook",
"secret": "8f2c1d9b4a7e6035c1d8b2f4a9e7c603",
"is_validated": false,
"is_active": false,
"consecutive_failures": 0,
"last_failure_at": null,
"account_id": 1,
"created_at": "2026-08-27T10:15:00.000000Z",
"updated_at": "2026-08-27T10:15:00.000000Z",
"events": [
{
"id": 41,
"name": "contact-created",
"webhook_id": 12,
"created_at": "2026-08-27T10:15:00.000000Z",
"updated_at": "2026-08-27T10:15:00.000000Z"
}
]
},
"message": "Entity was created successfully."
}| الرمز | المعنى |
|---|---|
| 402 | باقتك لا تشمل خطافات الويب، أو أنك بلغت الحد الأقصى لعدد الخطافات. |
| 422 | الرابط ليس عنوان https صالحاً، أو أن أحد الأحداث غير موجود. |
PUT https://app.alaaqat.com/api/account/webhooks/{id}
حيث id هو معرّف الخطاف. تتطلب صلاحية webhook-update.
محتوى الطلب مطابق لمحتوى الإنشاء، و events تستبدل قائمة الاشتراك الحالية — أرسل القائمة الكاملة التي تريد الاحتفاظ بها لا الإضافات فقط.
{warning} تغيير
URLيعيدis_validatedإلىfalse، وتتوقف الإرسالات حتى توثّق الخطاف من جديد.
200 OK مع بيانات الخطاف بعد التعديل والرسالة Entity was modified successfully.
POST https://app.alaaqat.com/api/account/webhooks/{id}/validate
ترسل طلب التحقق إلى رابطك. تتطلب صلاحية webhook-update. لا تحتاج إلى محتوى في الطلب.
راجع توثيق الرابط لمعرفة الرد الذي يجب أن يعيده خادمك بالضبط.
200 OK مع بيانات الخطاف وقد أصبح فيها "is_validated": true.
وإذا لم يُجب الرابط بشكل صحيح، يبقى الخطاف غير موثق وتكون الاستجابة:
{
"message": "Unable to validate the webhook. Please ensure that the secret key is correct and the webhook endpoint is properly configured."
}برمز الحالة 403.
PUT https://app.alaaqat.com/api/account/webhooks/{id}/activate
تتطلب صلاحية webhook-update، ويجب أن يكون الخطاف موثقاً مسبقاً وإلا رُفض الطلب برمز 403.
{
"is_active": true
}| الحقل | مطلوب | التحقق | الوصف |
|---|---|---|---|
| is_active | مطلوب | boolean | true لبدء الإرسالات و false لإيقافها |
وبهذه النقطة نفسها تعيد تشغيل خطاف ألغت علاقات تفعيله بعد تكرار الفشل: يبقى الخطاف موثقاً، فيكفي طلب واحد بـ is_active: true بعد أن يصبح رابطك سليماً.
200 OK. لا تحمل الاستجابة محتوى ذا فائدة؛ اقرأ الخطاف من نقطة نهاية القائمة إن أردت تأكيد الحالة الجديدة.
DELETE https://app.alaaqat.com/api/account/webhooks/{id}
تتطلب صلاحية webhook-delete. يُحذف الخطاف واشتراكاته بالأحداث نهائياً وتتوقف الإرسالات فوراً.
{
"message": "Entity was deleted successfully.",
"data": []
}# 1. إنشاء خطاف الويب
curl -X POST https://app.alaaqat.com/api/account/webhooks \
-H "Authorization: Bearer {مفتاحك هنا}" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{"URL":"https://yourdomain.com/alaaqat-webhook","events":["contact-created","contact-updated"]}'
# 2. توثيقه (يجب أن يجيب خادمك على طلب التحقق)
curl -X POST https://app.alaaqat.com/api/account/webhooks/12/validate \
-H "Authorization: Bearer {مفتاحك هنا}" \
-H "Accept: application/json"
# 3. تفعيله
curl -X PUT https://app.alaaqat.com/api/account/webhooks/12/activate \
-H "Authorization: Bearer {مفتاحك هنا}" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{"is_active":true}'