> ## Documentation Index
> Fetch the complete documentation index at: https://knowledge.flowella.io/llms.txt
> Use this file to discover all available pages before exploring further.

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

> اشترك في أحداث الرسائل والمحادثات وإلغاء الاشتراك والقوالب عبر webhooks، وتحقق من توقيعات HMAC، وتعامل مع إعادة المحاولات وتجنب التكرار.

تتيح "webhooks" الصادرة لأنظمتك الاستجابة للأحداث في Flowella
في الوقت الفعلي تقريبًا، دون الحاجة إلى استقصاء واجهة برمجة التطبيقات (API). يمكنك تكوين عنوان URL وقائمة بأنواع الأحداث، وسيقوم Flowella
بإرسال حزمة بيانات JSON موقعة عبر طلب POST إلى ذلك العنوان كلما وقع أحد تلك الأحداث.

## تكوين webhook

تحتاج إلى دور **المالك** أو **المسؤول**.

<Steps>
  <Step title="افتح الإعدادات → خطاف الويب">
    في تطبيق Flowella
    ، انتقل إلى **الإعدادات → Webhooks**.
  </Step>

  <Step title="إضافة خطاف ويب">
    انقر على **إضافة webhook**، والصق عنوان URL HTTPS العام لنقطة النهاية الخاصة بك، واختر أنواع الأحداث التي تريد تلقيها.
  </Step>

  <Step title="حفظ سر التوقيع">
    Flowella
    يقوم بإنشاء سر توقيع فريد لـ webhook. انسخه — ستستخدمه للتحقق من الطلبات الواردة.
  </Step>

  <Step title="إرسال اختبار">
    انقر على **إرسال اختبار** لإرسال حمولة`webhook.test`
    على الفور. تحقق من أن نقطة النهاية الخاصة بك قد استلمتها وردت بـ 2xx.
  </Step>
</Steps>

## أنواع الأحداث

يمكنك الاشتراك في أي من أحداث المنتج هذه:

| الحدث                                                      | متى يتم تشغيله |
| ---------------------------------------------------------- | -------------- |
| `message.received`                                         |                |
| وصول رسالة واردة WhatsApp                                  |                |
| من جهة اتصال                                               |                |
| `message.sent`                                             |                |
| Flowella                                                   |                |
| قبل رسالتك الصادرة وأرسلها إلى Meta                        |                |
|                                                            |                |
| `message.delivered`                                        |                |
| Meta                                                       |                |
| أكد تسليم الرسالة إلى جهاز المستلم                         |                |
| `message.read`                                             |                |
| فتح المستلم الرسالة                                        |                |
| `message.failed`                                           |                |
| Meta                                                       |                |
| أرجع فشلًا للرسالة                                         |                |
| `conversation.opened`                                      |                |
| انتقلت المحادثة إلى الحالة المفتوحة                        |                |
| `conversation.closed`                                      |                |
| تم إغلاق محادثة                                            |                |
| `optout.created`                                           |                |
| قام أحد جهات الاتصال بإلغاء الاشتراك في قناة معينة         |                |
| `template.status_updated`                                  |                |
| قام Meta                                                   |                |
| بتغيير حالة القالب (موافق عليه، مرفوض، متوقف مؤقتًا، معطل) |                |

يتم إرسال`webhook.test`
فقط عند النقر فوق **إرسال اختبار** — ولا يتم الاشتراك فيه بشكل صريح.

## تنسيق الطلب

يقوم Flowella
بإرسال نص JSON إلى عنوان URL الخاص بك باستخدام الرؤوس التالية:

```http theme={null}
POST https://your-endpoint.example.com/flowella
Content-Type: application/json
User-Agent: Flowella -Webhooks/1
X-Flowella-Signature: <hex digest>
```

يبلغ الحد الأقصى لحجم الحمولة **256 كيلوبايت**. يتم تلخيص الكائنات الأكبر حجمًا — استخدم واجهة برمجة التطبيقات (API) لجلب السجل الكامل حسب المعرف إذا كنت بحاجة إلى ذلك.

يختلف شكل النص الأساسي حسب الحدث ولكنه يتضمن دائمًا:

```json theme={null}
{
  "event": "message.delivered",
  "timestamp": "2025-01-15T14:30:00.000Z",
  "organizationId": "clxxxxxxxxxxxxxxxxxxxxxxxx",
  "data": { "...event-specific fields..." }
}
```

## التحقق من التوقيعات

يتضمن كل طلب رأس`X-Flowella-Signature`
. القيمة هي **ملخص HMAC-SHA256 سداسي عشري** لـ **نص الطلب الخام بتنسيق UTF-8** المشفر باستخدام سر التوقيع الخاص بـ webhook الخاص بك.

التحقق قبل المعالجة:

```js theme={null}
import { createHmac, timingSafeEqual } from "node:crypto";

function verify(rawBody, signatureHeader, secret) {
  const expected = createHmac("sha256", secret).update(rawBody).digest("hex");
  const a = Buffer.from(expected, "hex");
  const b = Buffer.from(signatureHeader, "hex");
  return a.length === b.length && timingSafeEqual(a, b);
}
```

```python theme={null}
import hmac, hashlib

def verify(raw_body: bytes, signature_header: str, secret: str) -> bool:
    expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature_header)
```

<Warning>
  قم دائمًا بالتوقيع على **بايتات نص الرسالة الأولية** قبل أي تحليل JSON أو إعادة تنسيق الحمولة بواسطة البرامج الوسيطة. إذا أعاد إطار العمل الخاص بك تسلسل JSON، فلن تتطابق التوقيعات.
</Warning>

## الردود والمحاولات المتكررة ومهلة الانتظار

* **مهلة**: ينتظر Flowella
  ما يصل إلى **10 ثوانٍ** حتى تستجيب نقطة النهاية الخاصة بك.
* **النجاح**: يتم التعامل مع أي استجابة`2xx`
  على أنها تسليم ناجح.
* **إعادة المحاولة**: يتم إعادة محاولة عمليات التسليم الفاشلة حتى **3 محاولات** مع التراجع.
* **التعطيل التلقائي**: إذا تراكمت **10 حالات فشل متتالية** في webhook، فإن Flowella
  يقوم بتعطيله. ستحتاج إلى إعادة تنشيطه من **الإعدادات → Webhooks** بعد إصلاح نقطة النهاية الخاصة بك.

يجب أن تعود نقطة النهاية الخاصة بك بأسرع ما يمكن — قم بتأجيل أي معالجة ثقيلة إلى قائمة انتظار في الخلفية من جانبك.

## التبعية

قد يتم إعادة محاولة الويب هوك، لذا قد يصل نفس الحدث المنطقي أكثر من مرة. للمعالجة بأمان:

* استخدم`data.id`
  الخاص بالحدث (أو مفتاح مشتق مثل`event + data.messageId`
  ) كمفتاح تبعية.
* احتفظ بذاكرة تخزين مؤقتة قصيرة الأمد للمفاتيح المعالجة (تكفي بضع ساعات لإعادة المحاولة).
* تعامل مع التكرارات على أنها لا تؤدي إلى أي عمل.

## سرد وإدارة عمليات التسليم

**الإعدادات → Webhooks** تعرض محاولات التسليم الأخيرة لكل Webhook، بما في ذلك:

* الطابع الزمني
* نوع الحدث
* حالة الاستجابة
* نص استجابة مقتطع (حتى \~1 كيلوبايت) للتصحيح

إذا تم تعطيل webhook بسبب فشل متكرر، تتيح لك نفس الصفحة إعادة تنشيطه.

## التطوير المحلي

إن أبسط طريقة للتطوير باستخدام webhooks محليًا هي إعادة توجيه نفق عام (على سبيل المثال، ngrok أو Cloudflare Tunnel) إلى خادم التطوير الخاص بك وتوجيه عنوان URL الخاص بـ webhook إلى مضيف النفق. استخدم **إرسال اختبار** لإطلاق الحمولات عند الطلب دون انتظار نشاط حقيقي من WhatsApp
.

<Tip>
  هل تحتاج إلى الاستجابة لأحداث غير موجودة في القائمة؟ أخبرنا على [الدعم](https://flowella.io/support) — نضيف الأحداث بناءً على طلب العملاء.
</Tip>

## ذات صلة

<CardGroup cols={2}>
  <Card title="الإعدادات → خطاف الويب" icon="webhook" href="/ar/settings/webhooks">
    تكوين نقاط النهاية وأسرار التوقيع ومحاولات إعادة التشغيل في التطبيق.
  </Card>

  <Card title="مقدمة واجهة برمجة التطبيقات" icon="code" href="/ar/api-reference/introduction">
    المصادقة والأخطاء وترقيم الصفحات وحدود المعدل لواجهة برمجة التطبيقات REST.
  </Card>

  <Card title="مفاتيح واجهة برمجة التطبيقات" icon="key" href="/ar/settings/api-keys">
    إنشاء وتناوب الرموز المميزة للحامل التي قد تحتاجها نقطة النهاية الخاصة بك.
  </Card>

  <Card title="أحداث الإخطار" icon="bell" href="/ar/app/notification-events">
    نفس الأحداث التي يتم تسليمها إلى موجز التطبيق والبريد الإلكتروني.
  </Card>
</CardGroup>