Webhook'lar — sistemlerinizde gerçek zamanlı moderasyon olayları

1Webhook'lar ne yapar

API'yi yoklamak yerine, bir URL kaydedersiniz ve grubunuzda bir şey olduğunda Telm ona imzalı bir HTTP POST gönderir. Moderasyon olaylarını kendi sistemlerinize — bir kontrol paneli, bir veri ambarı, bir uyarı kanalı — gerçek zamanlı olarak bu şekilde alırsınız.

Webhook uç noktalarını API üzerinden yönetirsiniz: bir URL kaydedin, hangi olaylara abone olacağınızı seçin, isteğe bağlı olarak onları belirli gruplarla sınırlayın, bir test ping'i gönderin ve son teslimat günlüğünü okuyun.

2Neden itmek yoklamayı yener

Yeni olayları bulmak için günlük uç noktasını bir zamanlayıcıyla çağırabilirsiniz, ancak bu gecikme ekler, kota harcar ve bir şeyin olduğu tam anı kaçırabilir. Webhook'lar modeli tersine çevirir: Telm size bir olay tetiklendiği anda söyler, böylece sistemleriniz saniyeler içinde tepki verir.

Tipik kullanımlar arasında yasakları kendi yönetim araçlarınıza yansıtmak, bir baskın algılandığında bir ekip kanalını uyarmak, algılamaları analize akıtmak veya bir üye katıldığında ya da ayrıldığında bir iş akışını tetiklemek yer alır.

• Gerçek zamanlı: bir olayı bir sonraki yoklamanızda değil, olduğu anda öğrenirsiniz.
• Verimli: günlük kotanızı yiyen tekrarlanan okumalar yok.
• Eksiksiz: teslimatlar yeniden denenir, böylece sizin tarafınızdaki kısa bir kesinti olayları kaybetmez.

3Abone olabileceğiniz olaylar

Spam kararlarını, cezaları ve üyelik değişikliklerini kapsayan yedi abone olunabilir olay türü vardır. Tek bir denetlenen mesaj birden fazla olay üretebilir — bir yasakla sonuçlanan bir spam mesajı hem spam.detected hem de user.banned yayar.

• spam.detected — motor bir mesajı spam olarak işaretledi.
• message.suspicious — puanlı bir gölge (izleme modu) algılaması.
• user.banned — bir üye yasaklandı.
• user.kicked — bir üye kaldırıldı.
• user.muted — bir üye susturuldu.
• user.joined — bir üye gruba katıldı.
• user.left — bir üye gruptan ayrıldı.

4Yük zarfı

Her teslimat, küçük, kararlı bir üst düzey alan kümesi ve içinde olaya özel bir veri nesnesi barındıran bir JSON zarfıdır. Ayrıntıları gerekene kadar ayrıştırmadan tür ve zamana göre yönlendirebilirsiniz.

• id — benzersiz bir teslimat kimliği; aynı olayın yeniden teslimatları aynı kimliği yeniden kullanır, tekilleştirmeyi bu şekilde yaparsınız.
• type — olay türü, yukarıdaki yediden biri.
• created_at — olayın tetiklendiği an, RFC3339 UTC olarak.
• group_id — olayın ait olduğu grup (uygun olduğunda).
• data — olaya özel bir nesne: spam olayları için mesaj ve karar ayrıntıları, üyelik olayları için üye ayrıntıları.

5Teslimatların gerçekten Telm'den olduğunu doğrulama

Her teslimat imzalanır, böylece sunucunuz isteğin gerçekten Telm'den geldiğini ve aktarım sırasında değiştirilmediğini doğrulayabilir. Yüke güvenmeden önce imzayı doğrulayın ve eşleşmeyen her şeyi reddedin.

İmza, zaman damgasının ve ham istek gövdesinin, uç nokta imzalama gizli değerinizle anahtarlanmış bir HMAC-SHA256'sıdır. Doğrulamak için, zaman damgası başlığı ve aldığınız tam baytlar üzerinde HMAC'yi yeniden hesaplayın ve onu imza başlığıyla karşılaştırın.

• X-Telm-Signature — imza, v1 ardından zaman damgasının gövdeye birleştirildiği onaltılık HMAC-SHA256 biçiminde.
• X-Telm-Timestamp — imzalanan unix-saniye zaman damgası, böylece eski veya yeniden oynatılan teslimatları reddedebilirsiniz.
• X-Telm-Event — olay türü ve X-Telm-Delivery — tekilleştirme için teslimat kimliği.
• İmzalama gizli değeri uç noktayı oluşturduğunuzda bir kez gösterilir ve whsec_ ile başlar. Onu güvenle saklayın; bir teslimatın gerçek olduğunu kanıtlayan tek şey odur.

6Güvenilir, tekilleştirilmiş teslimat

Teslimat en-az-bir-kezdir: Telm bir olayın size ulaşmasını sağlar, bu da aynı olayın ara sıra iki kez gelebileceği anlamına gelir. Her yeniden teslimat aynı teslimat kimliğini yeniden kullandığından, işlediğiniz kimlikleri saklayıp tekrarları atlayarak tekilleştirirsiniz.

Uç noktanıza ulaşılamıyorsa veya bir hata döndürüyorsa, teslimat sabit bir programa göre yeniden denenir — kabaca bir dakika, beş dakika, otuz dakika, iki saat ve altı saat sonra, yaklaşık sekiz buçuk saat boyunca altı denemeye kadar. Başarısız olmaya devam eden bir uç nokta, her iki tarafı da korumak için otomatik olarak devre dışı bırakılır ve sahibi bilgilendirilir.

• Bir 2xx durumuyla hızlıca yanıt verin; ağır işi onayladıktan sonra eşzamansız yapın.
• Teslimat kimliğine göre tekilleştirin — asla yük içeriğine göre değil.
• 72 saatlik bir pencere içinde hiç başarı olmadan üst üste yaklaşık yirmi kez başarısız olan bir uç nokta otomatik olarak devre dışı bırakılır; sunucunuz sağlıklı olduğunda onu yeniden etkinleştirin.

7Uç noktaları yönetme ve günlüğü okuma

Webhook uç noktalarını API üzerinden kaydeder, düzenler ve kaldırırsınız. Birini oluşturduğunuzda imzalama gizli değerini tam olarak bir kez alırsınız, abone olunacak olayları seçersiniz ve isteğe bağlı olarak onu belirli gruplarla sınırlarsınız. Bir test çağrısı imzalı bir ping gönderir, böylece gerçek trafik başlamadan önce doğrulamanızın çalıştığını teyit edebilirsiniz.

Her uç nokta, neyin gönderildiğini, ne zaman ve başarılı olup olmadığını görmek için geri okuyabileceğiniz bir teslimat günlüğü tutar — bir sonraki canlı olayı beklemeden bir alıcıyı hata ayıklamak için kullanışlıdır.

• Bir uç nokta oluşturun ve whsec_ gizli değerini hemen kopyalayın.
• İmza kontrolünüzü uçtan uca doğrulamak için bir test ping'i gönderin.
• Bir uç noktayı tek bir gruba sınırlayın veya yönettiğiniz tüm gruplara açık bırakın.
• Son denemeleri ve sonuçlarını incelemek için teslimat günlüğünü okuyun.

8En iyi uygulamalar ve sık yapılan hatalar

Sağlam bir alıcı, en yaygın sorunları önleyen birkaç kurala uyar.

• İmzayı ham gövde baytları üzerinde doğrulayın — önce JSON'a ayrıştırıp yeniden serileştirmek baytları değiştirebilir ve kontrolü bozabilir.
• Hızlıca 2xx döndürün ve daha sonra işleyin; yavaş bir işleyici zaman aşımlarına ve gereksiz yeniden denemelere neden olur.
• İşlemeyi bağımsız (idempotent) yapın, böylece yeniden teslim edilen bir olay çift saymaz.
• Herkese açık erişilebilir bir URL'de HTTPS kullanın; Telm iç ve özel adresleri engeller ve yönlendirmeleri izlemez.
• whsec_ gizli değerini günlüklerin ve istemci kodunun dışında tutun.