يمكن لـ Telm دفع أحداث الإشراف إلى خادمك في الوقت الفعلي. تسجّل إندبوينت، وتختار أي الأحداث تستقبل، ويرسل Telm طلب POST موقَّعًا لكل منها. يحمل كل تسليم توقيع HMAC-SHA256 تتحقق منه بسرّ إندبوينتك. عمليات التسليم الفاشلة تُعاد وفق جدول؛ وإندبوينت لا يمكن الوصول إليه دائمًا يُعطَّل تلقائيًا.
1مظروف الحدث
كل ويب-هوك هو طلب HTTP POST بجسم JSON في مظروف مشترك. للمظروف id (معرّف تسليم فريد لإزالة التكرار)، وtype (اسم الحدث)، وطابع زمني created_at، وgroup_id الذي ينتمي إليه الحدث، وكائن data يعتمد شكله على نوع الحدث.
الـ id حتمي للأحداث الحقيقية، فإن سُلِّم الحدث نفسه مرتين — مثلًا بعد إعادة — تستقبل الـ id نفسه في المرتين. استخدم ترويسة X-Telm-Delivery (التي تعكس هذا الـ id) كمفتاح idempotency كي يعالج معالِجك كل حدث مرة واحدة فقط.
- حقول المظروف: id وtype وcreated_at وgroup_id وdata.
- type هو أحد أسماء الأحداث من الكتالوج أدناه.
- data يحمل الحقول الخاصة بالحدث.
- استخدم id (وترويسة X-Telm-Delivery) لإزالة تكرار عمليات الإعادة.
2كتالوج الأحداث
تشترك بإندبوينت في أي مجموعة فرعية من الكتالوج. يُطلَق spam.detected حين يسِم المحرك رسالة كبريد مزعج. ويُطلَق message.suspicious في وضع المراقبة، حين كان المحرك سيتصرف لكنه سجّل درجة ظل للرسالة فقط. أما أحداث الأعضاء فتغطي دخول الناس ومغادرتهم ومعاقبتهم.
حدث ping خاص: ليس جزءًا من الكتالوج القابل للاشتراك ويُرسَل فقط حين تُطلِق تسليمًا تجريبيًا لإندبوينت، كي تؤكد أن مستقبِلك وفحص توقيعك يعملان من طرف إلى طرف.
- spam.detected — صُنِّفت رسالة كبريد مزعج.
- message.suspicious — اكتشاف ظل (وضع المراقبة).
- user.banned وuser.kicked وuser.muted — طُبِّق إجراء إشراف.
- user.joined وuser.left — دخل عضو المجموعة أو غادرها.
- ping — حدث تجريبي يدوي، لا يُطلَق أبدًا بنشاط حقيقي.
3حقول الحمولة لكل حدث
لـ spam.detected وmessage.suspicious، يحمل كائن data الحقول message_id وuser_id وusername ونص الرسالة (مقتطَع للرسائل الطويلة جدًا) والإجراء المُتَّخَذ وcategory وreason واللغة المُكتشَفة ودرجة ثقة. ويحمل message.suspicious إضافةً درجة الظل.
لأحداث الأعضاء (user.joined وuser.left وuser.banned وuser.kicked وuser.muted)، يحمل كائن data الحقول user_id وusername وfirst_name وmessage_id اختياريًا وreason حيث ينطبق. حدث كامن واحد يمكن أن ينتج أكثر من ويب-هوك — رسالة بريد مزعج تُطلِق حظرًا تُسلَّم كـ spam.detected وuser.banned معًا.
- أحداث البريد المزعج: message_id وuser_id وusername وtext وaction وcategory وreason وlanguage وconfidence (مع score لـ message.suspicious).
- أحداث الأعضاء: user_id وusername وfirst_name وmessage_id وreason.
- حادثة واحدة قد تُصدِر عدة أحداث؛ اربطها بـ user_id وgroup_id.
4التحقق من توقيع HMAC
يُوقَّع كل تسليم كي تتأكد أنه جاء فعلًا من Telm ولم يُعبَث به. تحصل على سرّ إندبوينت (يبدأ بـ whsec_) مرة واحدة، حين تنشئ الإندبوينت. خزّنه واستخدمه للتحقق من كل طلب وارد.
للتحقق، خذ قيمة ترويسة X-Telm-Timestamp، وأضِف نقطة، ثم أضِف جسم الطلب الخام تمامًا، واحسب HMAC-SHA256 لتلك السلسلة مستخدمًا سرّ إندبوينتك مفتاحًا. رمّز النتيجة بالست عشري وابدأها بـ v1= — يجب أن تساوي ترويسة X-Telm-Signature. قارِن بمقارنة ثابتة الزمن، وارفض الطلب إن كان الطابع الزمني أقدم من بضع دقائق (خمس نقطة قطع جيدة) لحجب إعادة التشغيل.
- X-Telm-Event — نوع الحدث.
- X-Telm-Delivery — معرّف التسليم (مفتاح idempotency).
- X-Telm-Timestamp — ثوانٍ يونكس، موقَّعة لمنع إعادة التشغيل.
- X-Telm-Signature — v1= مع HMAC-SHA256 الست عشري للطابع الزمني ونقطة والجسم الخام.
5التسليم وعمليات الإعادة والتعطيل التلقائي
يُحتسَب التسليم ناجحًا فقط إن رد إندبوينتك بحالة 2xx. أي شيء آخر — رمز غير 2xx، أو انتهاء مهلة، أو خطأ اتصال — يُعامَل كفشل ويُعاد وفق جدول ثابت: فورًا، ثم بعد دقيقة، و5 دقائق، و30 دقيقة، وساعتين، و6 ساعات، لست محاولات تمتد نحو ثماني ساعات ونصف قبل إغلاق التسليم كفاشل.
إن ظل إندبوينت يفشل — عشرون فشلًا متتاليًا على الأقل دون أي تسليم ناجح لثلاثة أيام — يعطّله Telm تلقائيًا كي يتوقف عن الإرسال إلى عنوان ميت. يمكنك إعادة تفعيله من لوحة التحكم بمجرد أن يعود مستقبِلك سليمًا.
- النجاح = HTTP 2xx. ردّ بسرعة (خلال نحو عشر ثوانٍ) وأدِّ العمل الثقيل بشكل غير متزامن.
- جدول الإعادة: فوري، +دقيقة، +5د، +30د، +ساعتين، +6س (ست محاولات).
- يُعطَّل تلقائيًا بعد 20 فشلًا متتاليًا دون نجاح خلال 72 ساعة.
- تسجيل الويب-هوك يتطلب خطة Pro فأعلى.