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

​
تكوين webhook

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

افتح الإعدادات → خطاف الويب

في تطبيق Flowella ، انتقل إلى الإعدادات → Webhooks.
2

إضافة خطاف ويب

انقر على إضافة webhook، والصق عنوان URL HTTPS العام لنقطة النهاية الخاصة بك، واختر أنواع الأحداث التي تريد تلقيها.
3

حفظ سر التوقيع

Flowella يقوم بإنشاء سر توقيع فريد لـ webhook. انسخه — ستستخدمه للتحقق من الطلبات الواردة.
4

إرسال اختبار

انقر على إرسال اختبار لإرسال حمولةwebhook.test على الفور. تحقق من أن نقطة النهاية الخاصة بك قد استلمتها وردت بـ 2xx.

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

يمكنك الاشتراك في أي من أحداث المنتج هذه:
الحدثمتى يتم تشغيله
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 الخاص بك باستخدام الرؤوس التالية: 
POST https://your-endpoint.example.com/flowella
Content-Type: application/json
User-Agent: Flowella -Webhooks/1
X-Flowella-Signature: <hex digest>
يبلغ الحد الأقصى لحجم الحمولة 256 كيلوبايت. يتم تلخيص الكائنات الأكبر حجمًا — استخدم واجهة برمجة التطبيقات (API) لجلب السجل الكامل حسب المعرف إذا كنت بحاجة إلى ذلك. يختلف شكل النص الأساسي حسب الحدث ولكنه يتضمن دائمًا: 
{
  "event": "message.delivered",
  "timestamp": "2025-01-15T14:30:00.000Z",
  "organizationId": "clxxxxxxxxxxxxxxxxxxxxxxxx",
  "data": { "...event-specific fields..." }
}

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

يتضمن كل طلب رأسX-Flowella-Signature . القيمة هي ملخص HMAC-SHA256 سداسي عشري لـ نص الطلب الخام بتنسيق UTF-8 المشفر باستخدام سر التوقيع الخاص بـ webhook الخاص بك. التحقق قبل المعالجة: 
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);
}

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)
قم دائمًا بالتوقيع على بايتات نص الرسالة الأولية قبل أي تحليل JSON أو إعادة تنسيق الحمولة بواسطة البرامج الوسيطة. إذا أعاد إطار العمل الخاص بك تسلسل JSON، فلن تتطابق التوقيعات.

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

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

​
التبعية

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

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

الإعدادات → Webhooks تعرض محاولات التسليم الأخيرة لكل Webhook، بما في ذلك:
  • الطابع الزمني
  • نوع الحدث
  • حالة الاستجابة
  • نص استجابة مقتطع (حتى ~1 كيلوبايت) للتصحيح
إذا تم تعطيل webhook بسبب فشل متكرر، تتيح لك نفس الصفحة إعادة تنشيطه.

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

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

​
ذات صلة

الإعدادات → خطاف الويب

تكوين نقاط النهاية وأسرار التوقيع ومحاولات إعادة التشغيل في التطبيق.

مقدمة واجهة برمجة التطبيقات

المصادقة والأخطاء وترقيم الصفحات وحدود المعدل لواجهة برمجة التطبيقات REST.

مفاتيح واجهة برمجة التطبيقات

إنشاء وتناوب الرموز المميزة للحامل التي قد تحتاجها نقطة النهاية الخاصة بك.

أحداث الإخطار

نفس الأحداث التي يتم تسليمها إلى موجز التطبيق والبريد الإلكتروني.