Webhooks — أحداث إشراف في الوقت الحقيقي في أنظمتك

1ما تفعله الـ webhooks

بدل استطلاع الـ API، تسجّل عنواناً ويرسل Telm طلب HTTP POST موقّعاً إليه كلما حدث شيء في مجموعتك. هكذا تُدخِل أحداث الإشراف إلى أنظمتك الخاصة — لوحة تحكم، أو مستودع بيانات، أو قناة تنبيه — في الوقت الحقيقي.

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

2لماذا الدفع يتفوّق على الاستطلاع

يمكنك استدعاء نقطة نهاية السجلّ على مؤقّت للعثور على أحداث جديدة، لكن ذلك يضيف كموناً، وينفق حصّة، ويمكن أن يفوت اللحظة الدقيقة لحدوث شيء. تقلب الـ webhooks النموذج: يخبرك Telm لحظة إطلاق حدث، فتتفاعل أنظمتك في ثوانٍ.

الاستخدامات النموذجية تشمل عكس عمليات الحظر إلى أدوات الإدارة الخاصة بك، وتنبيه قناة فريق حين تُكتشَف غارة، وبثّ الاكتشافات إلى التحليلات، أو إطلاق سير عمل حين ينضمّ عضو أو يغادر.

• في الوقت الحقيقي: تعرف بالحدث وهو يحدث، لا عند استطلاعك التالي.
• فعّال: لا قراءات متكرّرة تلتهم حصّتك اليومية.
• كامل: تُعاد محاولة التسليمات، فعطل قصير من جانبك لا يُفقِد الأحداث.

3الأحداث التي يمكنك الاشتراك فيها

توجد سبعة أنواع أحداث قابلة للاشتراك، تغطّي أحكام البريد المزعج والعقوبات وتغييرات العضوية. يمكن أن تنتج رسالة مُشرَف عليها واحدة أكثر من حدث — رسالة بريد مزعج تنتهي بحظر تُصدِر spam.detected وuser.banned معاً.

• spam.detected — علّم المحرّك رسالة كبريد مزعج.
• message.suspicious — اكتشاف ظلّي (وضع المراقبة) بدرجة.
• user.banned — حُظِر عضو.
• user.kicked — أُزيل عضو.
• user.muted — كُتِم عضو.
• user.joined — انضمّ عضو إلى المجموعة.
• user.left — غادر عضو المجموعة.

4غلاف الحمولة

كل تسليم غلاف JSON بمجموعة صغيرة ثابتة من الحقول عالية المستوى وكائن data خاصّ بالحدث داخله. يمكنك التوجيه حسب النوع والوقت دون تحليل التفاصيل حتى تحتاجها.

• id — معرّف تسليم فريد؛ عمليات إعادة تسليم الحدث نفسه تعيد استخدام المعرّف نفسه، وهكذا تزيل التكرار.
• type — نوع الحدث، أحد السبعة أعلاه.
• created_at — متى أُطلِق الحدث، بصيغة RFC3339 UTC.
• group_id — المجموعة التي ينتمي إليها الحدث (عند الانطباق).
• data — كائن خاصّ بالحدث: تفاصيل الرسالة والحكم لأحداث البريد المزعج، وتفاصيل العضو لأحداث العضوية.

5التحقّق من أن التسليمات من Telm فعلاً

كل تسليم موقّع فيستطيع خادمك تأكيد أن الطلب جاء فعلاً من Telm ولم يُعبَث به أثناء النقل. تحقّق من التوقيع قبل أن تثق بالحمولة، وارفض أي شيء لا يطابق.

التوقيع HMAC-SHA256 للطابع الزمني ومتن الطلب الخام، مُفتَّح بسرّ توقيع نقطة نهايتك. للتحقّق، أعِد حساب الـ HMAC على رأس الطابع الزمني والبايتات بالضبط التي تلقّيتها، وقارنه برأس التوقيع.

• X-Telm-Signature — التوقيع، منسّق كـ v1 متبوعاً بـ HMAC-SHA256 السداسي عشري للطابع الزمني موصولاً بالمتن.
• X-Telm-Timestamp — الطابع الزمني بالثواني unix الموقّع، فتستطيع رفض التسليمات القديمة أو المُعاد تشغيلها.
• X-Telm-Event — نوع الحدث، وX-Telm-Delivery — معرّف التسليم لإزالة التكرار.
• يُعرَض سرّ التوقيع مرة واحدة حين تُنشئ نقطة النهاية ويبدأ بـ whsec_. خزّنه بأمان؛ هو الشيء الوحيد الذي يثبت أن تسليماً حقيقي.

6تسليم موثوق ومُزال التكرار

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

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

• استجب بسرعة بحالة 2xx؛ أنجِز العمل الثقيل لا تزامنياً بعد الإقرار.
• أزِل التكرار على معرّف التسليم — لا على محتوى الحمولة أبداً.
• نقطة نهاية تفشل نحو عشرين مرة متتالية دون نجاح داخل نافذة 72 ساعة تُعطَّل تلقائياً؛ أعِد تفعيلها بمجرد أن يكون خادمك سليماً.

7إدارة نقاط النهاية وقراءة السجل

تسجّل وتحرّر وتزيل نقاط نهاية webhook عبر الـ API. حين تُنشئ واحدة تتلقّى سرّ التوقيع مرة واحدة بالضبط، وتختار الأحداث للاشتراك فيها، وتقصرها اختيارياً على مجموعات محدّدة. مكالمة اختبار ترسل ping موقّعاً فتستطيع تأكيد عمل تحقّقك قبل بدء الحركة الحقيقية.

تحتفظ كل نقطة نهاية بسجل تسليم يمكنك قراءته لرؤية ما أُرسِل، ومتى، وما إذا نجح — مفيد لتصحيح مُستقبِل دون انتظار الحدث الحيّ التالي.

• أنشئ نقطة نهاية وانسخ سرّ whsec_ فوراً.
• أرسل ping اختبار للتحقّق من فحص توقيعك من طرف لطرف.
• اقصر نقطة نهاية على مجموعة واحدة أو اتركها مفتوحة لكل المجموعات التي تديرها.
• اقرأ سجل التسليم لفحص المحاولات الأخيرة ونتائجها.

8أفضل الممارسات والأخطاء الشائعة

مُستقبِل متين يتبع بضع قواعد تمنع أشيع المشاكل.

• تحقّق من التوقيع على بايتات المتن الخام — التحليل إلى JSON أولاً وإعادة التسلسل يمكن أن يغيّر البايتات ويكسر الفحص.
• أعِد 2xx بسرعة وعالِج لاحقاً؛ معالج بطيء يسبّب انتهاءات مهلة وإعادات محاولة لا لزوم لها.
• اجعل المعالجة عديمة الأثر الجانبي (idempotent) فلا يحتسب حدث مُعاد التسليم مرتين.
• استخدم HTTPS على عنوان قابل للوصول علناً؛ يحظر Telm العناوين الداخلية والخاصة ولا يتبع عمليات إعادة التوجيه.
• أبقِ سرّ whsec_ خارج السجلّات وكود العميل.