الـ Webhook رابط تملكه أنت. تخبر لينوميا تشات بالأحداث التي تهمّك، وفي كل مرة يحدث واحد منها نرسل إلى ذلك
الرابط طلب POST بجسم JSON. وهو الطريقة التي يتفاعل بها نظام خارج المنتج مع ما يحدث داخله.

## متى تستخدمه

عندما يحتاج نظام آخر أن يعرف: أداة تذاكر تفتح حالة عند إنشاء محادثة، أو لوحة تحصي الرسائل الواردة، أو أداة أتمتة
تبدأ سلسلة عمل عند إضافة جهة اتصال.

## متى لا تستخدمه

- **لإرسال رسائل أو تغيير أي شيء.** فالـ Webhook صادر فقط. استخدم الواجهة البرمجية للكتابة.
- **للرد على محادثة فوراً.** فما يعيده رابطك يُهمَل. ولا شيء يعيده يدخل المحادثة.
- **لقاعدة واحدة بعينها.** إن أردت طلب POST عند تحقّق شرط معيّن فقط، فإجراء الـ Webhook داخل
  [قاعدة أتمتة](automation-rules) أو [تدفق](flow-builder) أضيق وأرخص من الاشتراك بكل رسالة في الحساب.

## ما تحتاجه أولاً

حساب مدير، ورابط يمكن الوصول إليه من الإنترنت العام عبر HTTP أو HTTPS ويجيب في ثوانٍ قليلة. وفي بعض الخطط تعرض
صفحة الـ Webhook إشعار ترقية بدلاً من القائمة.

## الخطوات

1. اذهب إلى **الإعدادات ← خيارات الربط ← Webhook** واختر **إضافة Webhook جديد**.
2. أدخل الرابط، وأعطه اسماً، وأشّر على الأحداث التي تريدها. وحدث واحد على الأقل مطلوب.
3. احفظ. ويُعرض الـ Secret مرة واحدة في شاشة التأكيد، فانسخه حينها. ويمكنك كشفه لاحقاً من نموذج تعديل الـ Webhook.

## الأحداث

يعرض النموذج عشرة أحداث. وحدث حادي عشر، `inbox_updated`، لا يظهر إلا إذا كانت أحداث قنوات التواصل مفعّلة على
تثبيتك.

| الحدث | يُطلق عند |
|---|---|
| `conversation_created` | فتح محادثة |
| `conversation_updated` | تغيّر أي خاصية في محادثة |
| `conversation_status_changed` | تغيّر حالتها |
| `message_created` | إضافة رسالة |
| `message_updated` | تغيّر رسالة |
| `contact_created` | إضافة جهة اتصال |
| `contact_updated` | تغيّر خصائص جهة اتصال |
| `webwidget_triggered` | فتح زائر أداة الدردشة المباشرة |
| `conversation_typing_on` / `conversation_typing_off` | بدء أحدهم الكتابة أو توقفه |
| `inbox_updated` | تغيّر إعدادات قناة تواصل |

وتوقّع أمرين. `conversation_updated` كثير الضجيج — فهو يُطلق على تغييرات لا تسمّيها تحديثاً، فرشّح على
`changed_attributes` بدلاً من اعتبار كل واحد خبراً. ولا تُرسل إلا الرسائل الواردة والصادرة ورسائل القوالب؛ أما
الملاحظات الخاصة وأسطر النشاط فلا.

## الحمولة

كل جسم كائن JSON فيه مفتاح `event` يسمّي الحدث، ومعه الكائن الذي يتعلق به الحدث.

| مجموعة الأحداث | يحمل الجسم |
|---|---|
| أحداث الرسائل | الرسالة — `id` و`content` و`content_type` و`message_type` و`private` و`source_id` والمرفقات إن وُجدت — ومعها `conversation` و`inbox` و`sender` و`account` |
| أحداث المحادثات | المحادثة — `id` و`status` و`priority` و`labels` و`inbox_id` و`meta` بالمُرسل والمُسند إليه والفريق، و`custom_attributes` والأوقات — وأحدث رسالة فيها، و`account` |
| أحداث جهات الاتصال | جهة الاتصال — `id` و`name` و`email` و`phone_number` و`identifier` و`avatar` و`custom_attributes` و`additional_attributes` و`blocked` — و`account` |

والأحداث الثلاثة التي تعني تغيّراً — `conversation_updated` و`conversation_status_changed`
و`contact_updated` — تضيف مصفوفة `changed_attributes` تصف ما تحرّك. و`contact_updated` و`inbox_updated` لا
تُرسل أصلاً إن لم يتغيّر شيء.

## التحقق من الإرسال

لكل Webhook سِرّ خاص به، ويحمل الإرسال الموقَّع ثلاث ترويسات طلب: معرّف الإرسال، والوقت، والتوقيع. وقيمة
التوقيع هي `sha256=` يتبعها HMAC-SHA256 للوقت ثم نقطة ثم جسم الطلب **الخام**، بمفتاح السِرّ:

```
sha256=HMAC_SHA256(secret, "<timestamp>.<raw body>")
```

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

وأسماء الترويسات الثلاث بدقة:

| الترويسة | ما تحمله |
|---|---|
| `X-Chatwoot-Signature` | `sha256=` يتبعها HMAC أعلاه |
| `X-Chatwoot-Timestamp` | الوقت الذي حُسب التوقيع عليه |
| `X-Chatwoot-Delivery` | معرّف الإرسال، حين يتوفّر |

وهذه الأسماء جزء من صيغة البروتوكول، ولا تتغيّر بتغيّر الهوية البصرية للتثبيت.

## عند فشل الإرسال

هذا الجزء يستحق قراءتين. فإرسال الـ Webhook **يُحاوَل مرة واحدة**.

| | ما يحدث |
|---|---|
| رابطك بطيء | يُترك الطلب بعد مهلة الـ Webhook في تثبيتك، وهي خمس ثوانٍ افتراضاً |
| رابطك يجيب 4xx أو 5xx | يُحسب الإرسال فاشلاً |
| رابطك متوقف | يُحسب الإرسال فاشلاً |
| أي ممّا سبق | يُكتب الفشل في سجل الخادم. ولا شيء يُعاد، ولا شيء يُحفظ في طابور، ولا شيء يُعرض لك |

فالأحداث التي تقع أثناء تعطّل رابطك تضيع. وإن كنت لا تستطيع تحمّل فقدانها، فاستقبل طلب POST في طابور خاص بك،
وأجب فوراً، ثم عالجه بعد ذلك.

## من يستطيع ذلك

المديرون وحدهم. فقائمة صلاحيات الدور المخصص لا تحتوي بنداً للـ Webhook، فلا يمكن تفويضه — راجع
[الأدوار والصلاحيات](roles-and-permissions).

## الحدود

- **لا إعادة محاولة، ولا سجل إرسال، ولا إعادة إرسال، ولا زر اختبار.** فالتحقق من Webhook يكون بإطلاق حدث حقيقي.
- **لا يتكرر الرابط نفسه في الحساب الواحد.** ولتصل الأحداث مرتين، استخدم رابطين مختلفين.
- **العناوين الخاصة والداخلية مرفوضة.** فالرابط الذي يُترجم إلى localhost أو إلى شبكة خاصة لا يُرسل إليه. ويجب أن
  يكون رابطك متاحاً للعموم.
- **`inbox_created` لا يمكن الاشتراك به من النموذج.** فهو موجود في قائمة أحداث الواجهة البرمجية وحدها.
- **جسم الرد لا يُقرأ أبداً**، ونوع محتوى الرد لا يُفحَص.
- **الحمولة غير قابلة للتهيئة.** فلا تضيف حقولاً ولا تحذف حقولاً ولا تختار صيغة.
- **الاشتراكات على مستوى الحساب.** فلا تشترك برسائل قناة تواصل واحدة فقط؛ رشّح على `inbox` في كودك.

## أشياء أخرى ترسل إلى رابط

الـ Webhook واحد من عدة. وهي غير متكافئة، والموقَّع منها بعضها فقط.

| يرسله | `event` في الجسم | موقَّع |
|---|---|---|
| اشتراك Webhook | الحدث الذي اشتركت به | نعم، بسِرّ الـ Webhook |
| إجراء الـ Webhook في [قاعدة أتمتة](automation-rules) | `automation_event.<trigger>`، ومعه كتلة `commerce` على مُطلِق المتجر | لا |
| إجراء الـ Webhook في [ماكروس](macros) | `macro.executed` | لا |
| عقدة الـ Webhook في [تدفق](flow-builder) | `flow_webhook`، ومعه التدفق والجلسة والقيم التي جمعها | نعم، بسِرّ روبوت التدفق |

## مواضيع ذات صلة

- [خيارات الربط](integrations)
- [قواعد الأتمتة](automation-rules) · [ماكروس](macros) · [منشئ التدفقات](flow-builder)
- [الأدوار والصلاحيات](roles-and-permissions)
- [عندما لا يعمل شيء](troubleshooting)

## إن لم ينجح الأمر

**لا يصل شيء.** تحقق بهذا الترتيب: الرابط متاح للعموم، ويجيب في أقل من خمس ثوانٍ، والحدث الذي تتوقعه مؤشَّر
فعلاً. والرابط على شبكة خاصة لا يستقبل شيئاً أبداً.

**بعض الأحداث تصل وبعضها لا.** فالملاحظات الخاصة وأسطر النشاط لا تُرسل كرسائل، و`contact_updated` يُمنع إن لم
يتغيّر شيء.

**فحص التوقيع عندي يفشل.** أنت تُجزّئ جسماً أعدت تحويله إلى نص على الأغلب. جزّئ البايتات الخام، وضمّن الوقت
والنقطة قبلها.

**فقدت أحداثاً أثناء انقطاع.** لا يوجد تعويض. اقرأ الواجهة البرمجية للفترة التي فاتتك.

**صفحة الـ Webhook تعرض إشعار ترقية.** فالواجهة البرمجية والـ Webhook غير مشمولين في خطتك.