Telm, moderasyon olaylarını sunucunuza gerçek zamanlı olarak iletebilir. Bir uç nokta kaydedersiniz, hangi olayları alacağınızı seçersiniz ve Telm her biri için imzalı bir POST gönderir. Her teslimat, uç nokta gizli bilginizle doğruladığınız bir HMAC-SHA256 imzası taşır. Başarısız teslimatlar bir programa göre yeniden denenir; kalıcı olarak ulaşılamayan bir uç nokta otomatik olarak devre dışı bırakılır.
1Olay zarfı
Her webhook, ortak bir zarf içinde JSON gövdeli bir HTTP POST'tur. Zarfta bir id (yinelenenleri ayıklamak için benzersiz bir teslimat tanımlayıcısı), bir type (olay adı), bir created_at zaman damgası, olayın ait olduğu group_id ve şekli olay türüne bağlı bir data nesnesi bulunur.
id, gerçek olaylar için belirlenimlidir, dolayısıyla aynı olay iki kez teslim edilirse — örneğin bir yeniden denemeden sonra — her iki seferde de aynı id'yi alırsınız. İşleyicinizin her olayı yalnızca bir kez işlemesi için X-Telm-Delivery başlığını (bu id'yi yansıtır) bir eşsizlik anahtarı olarak kullanın.
- Zarf alanları: id, type, created_at, group_id, data.
- type, aşağıdaki katalogdaki olay adlarından biridir.
- data, olaya özgü alanları taşır.
- Yeniden denemeleri ayıklamak için id'yi (ve X-Telm-Delivery başlığını) kullanın.
2Olay kataloğu
Bir uç noktayı katalogun herhangi bir alt kümesine abone edersiniz. spam.detected, motor bir mesajı spam olarak işaretlediğinde tetiklenir. message.suspicious, izleme modunda, motor eylemde bulunacakken mesajı yalnızca gölge puanladığında tetiklenir. Üye olayları, kişilerin girmesini, ayrılmasını ve cezalandırılmasını kapsar.
ping olayı özeldir: abone olunabilir katalogun parçası değildir ve yalnızca bir uç nokta için bir test teslimatını tetiklediğinizde gönderilir, böylece alıcınızın ve imza kontrolünüzün baştan sona çalıştığını doğrulayabilirsiniz.
- spam.detected — bir mesaj spam olarak sınıflandırıldı.
- message.suspicious — bir gölge (izleme modu) tespiti.
- user.banned, user.kicked, user.muted — bir moderasyon eylemi uygulandı.
- user.joined, user.left — bir üye gruba girdi veya ayrıldı.
- ping — gerçek etkinlik tarafından asla tetiklenmeyen manuel bir test olayı.
3Olay başına yük alanları
spam.detected ve message.suspicious için data nesnesi şunları taşır: message_id, user_id, username, mesaj metni (çok uzun mesajlar için kısaltılır), alınan eylem, bir kategori, bir neden, tespit edilen dil ve bir güven puanı. message.suspicious ek olarak gölge puanını taşır.
Üye olayları (user.joined, user.left, user.banned, user.kicked, user.muted) için data nesnesi şunları taşır: user_id, username, first_name, isteğe bağlı bir message_id ve geçerli olduğu yerde bir neden. Temel bir olay birden fazla webhook üretebilir — bir yasağı tetikleyen bir spam mesajı hem spam.detected hem de user.banned olarak teslim edilir.
- Spam olayları: message_id, user_id, username, text, action, category, reason, language, confidence (message.suspicious için ayrıca score).
- Üye olayları: user_id, username, first_name, message_id, reason.
- Tek bir olay birkaç olay yayabilir; bunları user_id ve group_id ile ilişkilendirin.
4HMAC imzasını doğrulamak
Her teslimat, gerçekten Telm'den geldiğinden ve değiştirilmediğinden emin olabilmeniz için imzalanır. Uç noktayı oluşturduğunuzda bir kez bir uç nokta gizli bilgisi (whsec_ ile başlar) alırsınız. Onu saklayın ve her gelen isteği doğrulamak için kullanın.
Doğrulamak için, X-Telm-Timestamp başlık değerini alın, bir nokta ekleyin, ardından tam ham istek gövdesini ekleyin ve uç nokta gizli bilginizi anahtar olarak kullanarak bu dizenin bir HMAC-SHA256'sını hesaplayın. Sonucu onaltılık kodlayın ve önüne v1= ekleyin — bu, X-Telm-Signature başlığına eşit olmalıdır. Sabit zamanlı bir karşılaştırmayla karşılaştırın ve tekrar oynatmaları engellemek için zaman damgası birkaç dakikadan (beş iyi bir sınırdır) eskiyse isteği reddedin.
- X-Telm-Event — olay türü.
- X-Telm-Delivery — teslimat id'si (eşsizlik anahtarı).
- X-Telm-Timestamp — unix saniyeleri, tekrar oynatmaları önlemek için imzalanmış.
- X-Telm-Signature — v1= artı zaman damgasının, bir noktanın ve ham gövdenin onaltılık HMAC-SHA256'sı.
5Teslimat, yeniden denemeler ve otomatik devre dışı bırakma
Bir teslimat, yalnızca uç noktanız bir 2xx durumuyla yanıt verirse başarılı sayılır. Başka herhangi bir şey — 2xx olmayan bir kod, bir zaman aşımı veya bir bağlantı hatası — başarısızlık olarak ele alınır ve sabit bir programa göre yeniden denenir: hemen, ardından 1 dakika, 5 dakika, 30 dakika, 2 saat ve 6 saat sonra; teslimat başarısız olarak kapatılmadan önce kabaca sekiz buçuk saati kapsayan altı deneme.
Bir uç nokta sürekli başarısız olursa — üç gün boyunca başarılı bir teslimat olmadan en az yirmi ardışık başarısızlık — Telm onu otomatik olarak devre dışı bırakır, böylece ölü bir URL'ye göndermeyi keser. Alıcınız tekrar sağlıklı olduğunda onu kontrol panelinden yeniden etkinleştirebilirsiniz.
- Başarı = HTTP 2xx. Hızlı yanıt verin (yaklaşık on saniye içinde) ve ağır işi eşzamansız yapın.
- Yeniden deneme programı: hemen, +1dk, +5dk, +30dk, +2sa, +6sa (altı deneme).
- 72 saat içinde başarı olmadan 20 ardışık başarısızlıktan sonra otomatik devre dışı bırakılır.
- Webhook kaydı Pro planı veya üstünü gerektirir.