Webhooks

تربط الـ Webhooks منصة dAio بأنظمتك الخاصة. فبدلاً من استجواب المنصة باستمرار، تدع dAio هو من يُنبّهك: فبمجرد وقوع حدث — تنبيه جوي مُفعَّل، أو خطر مرتفع مُكتشَف — يرسل dAio في الوقت الفعلي طلب HTTP موقَّعاً إلى نقطة النهاية التي تختارها. وبذلك تُؤتمت سير عملك: فتح التذاكر، والإشعارات الداخلية، وتحديث لوحة معلومات الأعمال، أو إطلاق خطة عمل ميدانية.

إنه الجسر بين التنبيهات في dAio ونظام معلوماتك.

نصيحة : ابدأ بـ webhook واحد فقط مشترك في نوع حدث واحد، وتحقق من السلسلة من طرف إلى طرف، ثم وسّع نطاقك. ستتجنّب إغراق أنظمتك بالإشعارات قبل أن تكون قد ضمنت موثوقية المعالجة.

تهيئة webhook

1. انتقل إلى الإعدادات > Webhooks.
2. انقر على webhook جديد.
3. أدخل عنوان URL للوجهة: نقطة نهاية HTTPS لخادمك (مثال https://votre-serveur.com/webhook).
4. اختر الأحداث المراد الاستماع إليها بالنقر على العلامات المقابلة.
5. أكِّد بالنقر على إنشاء.

يُولَّد سرّ تلقائياً عند الإنشاء. وهو يُستخدم لتوقيع كل طلب عبر HMAC-SHA256 (انظر أدناه): احتفظ به في جهة الخادم، فهو يتيح لك التحقق من أن كل استدعاء صادر فعلاً عن dAio.

تنبيه : يجب أن يكون عنوان URL بصيغة HTTPS ومتاحاً للعموم. لن تستطيع نقطة نهاية بصيغة HTTP بسيطة أو خلف جدار حماية مغلق استقبال عمليات التسليم.

الأحداث المتاحة

الحدث	الوصف
weather.alert	تم تفعيل تنبيه جوي على أحد المواقع
weather.threshold	تم تجاوز عتبة جوية مخصّصة
air_quality.alert	تم إصدار تنبيه لجودة الهواء
pollen.alert	تم إصدار تنبيه لحبوب اللقاح
marine.alert	تم إصدار تنبيه للأحوال البحرية
frost.alert	تم تفعيل تنبيه للصقيع
storm.alert	تم تفعيل تنبيه للعواصف الرعدية / العواصف
business.risk_high	تم اكتشاف مستوى خطر مرتفع على نشاطك

نصيحة : اشترك بكل webhook في الأحداث المستخدَمة فعلاً من قبل النظام المستقبِل فقط. لا تحتاج نقطة نهاية «التذاكر» إلى استقبال الأحداث ذاتها التي تستقبلها نقطة نهاية «لوحة المعلومات».

صيغة الحمولة (payload)

كل عملية تسليم هي طلب POST يكون جسمه كائن JSON. والبنية العامة كالتالي:

{
  "event": "weather.alert",
  "timestamp": "2026-06-30T08:15:00Z",
  "data": {
    "site_id": 42,
    "site_name": "Entrepôt Nord",
    "severity": "high",
    "message": "Vent fort attendu (rafales > 80 km/h)"
  }
}

يُحدّد الحقل event نوع الحدث، ويشير timestamp إلى تاريخ الإصدار (بالتوقيت العالمي UTC، بصيغة ISO 8601)، بينما يحتوي data على التفاصيل الخاصة بالحدث.

مصادقة HMAC-SHA256

يُوقَّع كل طلب بسرّك عبر HMAC-SHA256. ويُمرَّر التوقيع في الترويسة X-Daio-Signature، بالصيغة sha256=<signature>.

تحقّق من هذا التوقيع بشكل منهجي قبل معالجة أي طلب: فهذا ما يضمن أن الاستدعاء صادر عن dAio وأن الحمولة لم تُعدَّل.

التحقق في جهة الخادم (Python):

import hmac, hashlib

def verify_webhook(payload, signature, secret):
    expected = hmac.new(
        secret.encode(), payload, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

تنبيه : احسب التوقيع على الجسم الخام للطلب (البايتات المستلمة)، قبل أي إلغاء لتسلسل JSON. فأدنى إعادة تنسيق تُغيّر الـ hash وتُفشِل التحقق.

الاختبار وتصحيح الأخطاء

• انقر على أيقونة اختبار (▶) بجانب أحد الـ webhooks لإرسال حدث وهمي إلى نقطة نهايتك.
• يؤكّد رد HTTP بصيغة 2xx أن خادمك قد استقبل الطلب وقبِله.
• وسّع الـ webhook للاطلاع على آخر عمليات التسليم الخاصة به: رمز HTTP، ونوع الحدث، والطابع الزمني.
• تشير نقطة ملوّنة إلى حالة الـ webhook: أخضر = نشط، أحمر = مُعطَّل بعد إخفاقات متكررة.

سجل عمليات التسليم

يُسجَّل كل إرسال. وسّع أحد الـ webhooks لترى، عند كل محاولة:

• رمز HTTP للرد (أخضر إذا كان < 300، وأحمر خلاف ذلك)
• نوع الحدث المُسلَّم
• تاريخ ووقت المحاولة

يظهر عدّاد الإخفاقات على الـ webhook عند فشل بعض عمليات التسليم.

المحاولات والموثوقية

يعيد dAio محاولة التسليم تلقائياً عند الفشل، بفواصل زمنية متزايدة. لذا يجب أن تكون نقطة نهايتك مُتكافئة الأثر (idempotent): فقد تصل العملية ذاتها عدة مرات، ويجب أن تُنتج معالجتك النتيجة ذاتها دون أي أثر جانبي.

تنبيه : يجب أن تستجيب نقطة نهايتك في أقل من 10 ثوانٍ برمز HTTP بصيغة 2xx. وما يتجاوز ذلك، أو في حال وجود رمز خطأ، تُعتبر عملية التسليم فاشلة وستُعاد المحاولة. وبعد إخفاقات متكررة، يُعطَّل الـ webhook تلقائياً.

أفضل الممارسات

• تحقّق دائماً من توقيع HMAC قبل معالجة أي حمولة: لا تثق أبداً بطلب غير مُصادَق عليه.
• استجِب بسرعة: أعِد 200 فوراً، ثم عالِج عبء العمل في الخلفية. ستتجنّب مهل الانتهاء وإعادات المحاولة غير الضرورية.
• اجعل معالجتك مُتكافئة الأثر لاستيعاب عمليات التسليم المتعددة دون مخاطرة.
• رشِّح عند المصدر: اشترك بكل webhook في الأحداث المفيدة لنظامه المستقبِل فقط.
• راقب عدّاد الإخفاقات وسجل عمليات التسليم لاكتشاف نقطة نهاية معطّلة بسرعة قبل أن تُعطَّل.
• استخدم زر اختبار بعد كل تعديل من جهتك (نشر، تغيير عنوان URL) للتحقق من السلسلة دون انتظار حدث حقيقي.

نصيحة : اربط الـ webhooks الخاصة بك بـالتنبيهات وبإعداد فريقك لتوجيه المعلومة الصحيحة تلقائياً إلى النظام الصحيح. يعتمد توفّر الـ webhooks على اشتراكك.