Telm dapat mengirim peristiwa moderasi ke server Anda secara real-time. Anda mendaftarkan sebuah endpoint, memilih peristiwa mana yang akan diterima, dan Telm mengirim POST bertanda tangan untuk masing-masing. Setiap pengiriman membawa tanda tangan HMAC-SHA256 yang Anda verifikasi dengan rahasia endpoint Anda. Pengiriman yang gagal dicoba ulang sesuai jadwal; endpoint yang permanen tidak dapat dijangkau dinonaktifkan otomatis.
1Amplop peristiwa
Setiap webhook adalah HTTP POST dengan body JSON dalam sebuah amplop umum. Amplop memiliki id (pengidentifikasi pengiriman unik untuk deduplikasi), sebuah type (nama peristiwa), stempel waktu created_at, group_id tempat peristiwa itu berasal, dan sebuah objek data yang bentuknya bergantung pada jenis peristiwa.
id bersifat deterministik untuk peristiwa nyata, jadi jika peristiwa yang sama dikirim dua kali — misalnya setelah percobaan ulang — Anda menerima id yang sama pada keduanya. Gunakan header X-Telm-Delivery (yang mencerminkan id ini) sebagai kunci idempotensi agar handler Anda memproses setiap peristiwa hanya sekali.
- Bidang amplop: id, type, created_at, group_id, data.
- type adalah salah satu nama peristiwa dari katalog di bawah.
- data membawa bidang khusus peristiwa.
- Gunakan id (dan header X-Telm-Delivery) untuk mendeduplikasi percobaan ulang.
2Katalog peristiwa
Anda berlangganan sebuah endpoint ke subset mana pun dari katalog. spam.detected terpicu ketika mesin menandai sebuah pesan sebagai spam. message.suspicious terpicu dalam mode pemantauan, ketika mesin akan bertindak tetapi hanya menilai pesan itu secara bayangan. Peristiwa anggota mencakup orang yang masuk, keluar, dan dihukum.
Peristiwa ping bersifat khusus: ia bukan bagian dari katalog yang dapat dilangganani dan hanya dikirim ketika Anda memicu pengiriman uji untuk sebuah endpoint, sehingga Anda dapat memastikan penerima dan pemeriksaan tanda tangan Anda bekerja dari ujung ke ujung.
- spam.detected — sebuah pesan diklasifikasikan sebagai spam.
- message.suspicious — sebuah deteksi bayangan (mode pemantauan).
- user.banned, user.kicked, user.muted — sebuah tindakan moderasi diterapkan.
- user.joined, user.left — seorang anggota masuk atau keluar dari grup.
- ping — peristiwa uji manual, tidak pernah dipicu oleh aktivitas nyata.
3Bidang payload per peristiwa
Untuk spam.detected dan message.suspicious, objek data membawa message_id, user_id, username, teks pesan (dipotong untuk pesan yang sangat panjang), tindakan yang diambil, sebuah category, sebuah reason, bahasa yang terdeteksi, dan skor keyakinan. message.suspicious tambahan membawa skor bayangan.
Untuk peristiwa anggota (user.joined, user.left, user.banned, user.kicked, user.muted), objek data membawa user_id, username, first_name, sebuah message_id opsional, dan sebuah reason jika berlaku. Satu peristiwa yang mendasari dapat menghasilkan lebih dari satu webhook — sebuah pesan spam yang memicu pemblokiran dikirim sebagai spam.detected maupun user.banned.
- Peristiwa spam: message_id, user_id, username, text, action, category, reason, language, confidence (plus score untuk message.suspicious).
- Peristiwa anggota: user_id, username, first_name, message_id, reason.
- Satu insiden dapat memancarkan beberapa peristiwa; korelasikan mereka berdasarkan user_id dan group_id.
4Memverifikasi tanda tangan HMAC
Setiap pengiriman ditandatangani agar Anda dapat yakin ia benar-benar datang dari Telm dan tidak dirusak. Anda mendapat sebuah rahasia endpoint (ia diawali whsec_) satu kali, ketika Anda membuat endpoint. Simpan ia dan gunakan untuk memverifikasi setiap permintaan masuk.
Untuk memverifikasi, ambil nilai header X-Telm-Timestamp, tambahkan sebuah titik, lalu tambahkan body permintaan mentah yang persis, dan hitung HMAC-SHA256 dari string itu menggunakan rahasia endpoint Anda sebagai kunci. Kodekan hasilnya dalam heksadesimal dan beri awalan v1= — ia harus sama dengan header X-Telm-Signature. Bandingkan dengan perbandingan waktu-konstan, dan tolak permintaan jika stempel waktunya lebih tua dari beberapa menit (lima adalah batas yang baik) untuk memblokir serangan ulang.
- X-Telm-Event — jenis peristiwa.
- X-Telm-Delivery — id pengiriman (kunci idempotensi).
- X-Telm-Timestamp — detik unix, ditandatangani untuk mencegah serangan ulang.
- X-Telm-Signature — v1= plus HMAC-SHA256 heksadesimal dari stempel waktu, sebuah titik, dan body mentah.
5Pengiriman, percobaan ulang, dan penonaktifan otomatis
Sebuah pengiriman dihitung berhasil hanya jika endpoint Anda merespons dengan status 2xx. Apa pun selain itu — kode non-2xx, tenggat waktu, atau kesalahan koneksi — diperlakukan sebagai kegagalan dan dicoba ulang sesuai jadwal tetap: segera, lalu setelah 1 menit, 5 menit, 30 menit, 2 jam, dan 6 jam, untuk enam percobaan yang membentang sekitar delapan setengah jam sebelum pengiriman ditutup sebagai gagal.
Jika sebuah endpoint terus gagal — setidaknya dua puluh kegagalan berturut-turut tanpa pengiriman yang berhasil selama tiga hari — Telm otomatis menonaktifkannya agar ia berhenti mengirim ke URL yang mati. Anda dapat mengaktifkannya kembali dari dashboard setelah penerima Anda sehat lagi.
- Berhasil = HTTP 2xx. Respons cepat (dalam sekitar sepuluh detik) dan lakukan pekerjaan berat secara asinkron.
- Jadwal percobaan ulang: segera, +1m, +5m, +30m, +2j, +6j (enam percobaan).
- Dinonaktifkan otomatis setelah 20 kegagalan berturut-turut tanpa keberhasilan dalam 72 jam.
- Mendaftarkan webhook membutuhkan paket Pro atau lebih tinggi.