الـ Webhooks الصادرة

تتيح الـ Webhooks لـ FreeMaint إرسال طلب POST إلى عنوان تتحكم فيه بمجرد وقوع الحدث، فيبقى نظام آخر (ERP، فوترة، مخزون، محاسبة، قناة محادثة) متوافقاً دون إعادة إدخال يدوي. الإعداد من /company-settings/webhooks. باقة Starter محدودة بـ 100 تسليم/يوم؛ وBusiness وما فوقها غير محدودة. للاطلاع على المرجع الكامل للحمولات، راجع «API و GraphQL > Webhooks».

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

• work_order.created — تم إنشاء أمر عمل
• work_order.completed — انتقل أمر عمل إلى «مكتمل»
• work_order.status_changed — انتقل أمر عمل إلى أي حالة؛ ولا يزال work_order.completed يُطلَق أيضًا
• request.created — تم إرسال طلب صيانة
• request.status_changed — تمت الموافقة على طلب أو رفضه أو إلغاؤه
• part.low_stock — انخفضت قطعة إلى نقطة إعادة الطلب أو دونها
• part.out_of_stock — نفدت قطعة تمامًا
• part.low_stock_summary — مرة يوميًا، القطع التي بلغت نقطة إعادة الطلب أو دونها، بما فيها القطع التي لم تتحرك قط
• part.out_of_stock_summary — مرة يوميًا، القطع التي بلغت الصفر
• part.consumed — استُهلكت في أمر عمل أو أُرجعت منه
• compliance.chain_divergence — انكسرت سلسلة تجزئة التدقيق (Enterprise)
• asset.downtime_started — فُتح توقّف آلة
• asset.downtime_ended — أُغلق توقّف آلة
• report.daily_summary — أعمال اليوم المنجزة، مرة يوميًا في الساعة التي تختارها
• purchase_order.created — أُنشئ أمر شراء
• purchase_order.status_changed — انتقل أمر شراء إلى حالة أخرى (معتمد، مطلوب، ملغى…)
• purchase_order.received — استُلم تسليم لأمر شراء، بما في ذلك التسليمات الجزئية

دلالات التسليم

• طلب POST بجسم JSON: { event, timestamp, data }
• ترويسة X-FreeMaint-Signature — t=<ثوانٍ unix>,v1=<hex>، حيث v1 هو HMAC-SHA256 للسلسلة «<t>.<الجسم الخام>» بمفتاح هو سر الـ webhook لديك. تحقّق منها في كل طلب، مقابل الجسم الخام
• تُرسَل أيضاً X-FreeMaint-Event و X-FreeMaint-Delivery-Id
• تُعاد أخطاء الشبكة و5xx حتى 3 مرات بتراجع أُسّي (نحو 2 و4 و8 ثوانٍ)؛ أما 4xx فرفض نهائي ولا يُعاد
• تُسجَّل كل محاولة تحت الـ webhook مع حالتها ورمز الاستجابة وعدد المحاولات — ويمكن إعادة إرسال أي تسليم منتهٍ من هناك
• صور اختيارية: عند تفعيل «تضمين الصور» تحمل أحداث "work_order" و"request" ما يصل إلى 4 روابط صور في الحقل "photos"، صالحة لمدة 7 أيام لأي شخص يملكها — فعّل الخيار لنقطة نهاية تتحكم بها فقط

الإعداد

1. افتح /company-settings/webhooks — يتطلب صلاحية إعدادات الشركة أو صلاحية «إدارة التكاملات».
2. اضغط «إضافة Webhook» — امنحه اسماً وعنوان https:// وحدّد الأحداث المطلوبة.
3. انسخ سر التوقيع — يُعرض مرة واحدة فقط عند الإنشاء. ويمكنك لاحقاً توليد سر جديد عبر «تدوير السر»، ما يُبطل القديم.
4. راقب التسليمات — افتح سجل التسليمات الخاص بالـ webhook للتأكد من وصول الأحداث وإعادة إرسال ما أخفق.

الحدود حسب الباقة

• Starter — 100 تسليم/يوم لكل شركة (يُصفَّر العدّاد عند 00:00 UTC)
• Business — غير محدود
• Enterprise — غير محدود
• يحسب العدّاد المحاولات: ثلاثة webhooks على الحدث نفسه تستهلك ثلاث وحدات