Webhook — peristiwa moderasi waktu nyata di sistem Anda

1Apa yang dilakukan webhook

Alih-alih melakukan polling API, Anda mendaftarkan sebuah URL dan Telm mengirim HTTP POST yang ditandatangani ke URL itu setiap kali sesuatu terjadi di grup Anda. Begitulah cara Anda memasukkan peristiwa moderasi ke sistem Anda sendiri — dashboard, gudang data, saluran pemberitahuan — secara waktu nyata.

Anda mengelola endpoint webhook melalui API: mendaftarkan URL, memilih peristiwa mana yang akan dilanggan, secara opsional membatasinya ke grup tertentu, mengirim ping uji, dan membaca log pengiriman terbaru.

2Mengapa mendorong mengungguli polling

Anda bisa saja memanggil endpoint jurnal secara berkala untuk menemukan peristiwa baru, tetapi itu menambah latensi, menghabiskan kuota, dan bisa melewatkan momen persis sesuatu terjadi. Webhook membalik modelnya: Telm memberi tahu Anda seketika sebuah peristiwa terpicu, sehingga sistem Anda bereaksi dalam hitungan detik.

Penggunaan umum meliputi mencerminkan blokir ke alat admin Anda sendiri, memberi tahu saluran tim saat serangan terdeteksi, mengalirkan deteksi ke analitik, atau memicu alur kerja saat anggota bergabung atau keluar.

• Waktu nyata: Anda mengetahui sebuah peristiwa saat terjadi, bukan pada polling berikutnya.
• Efisien: tanpa pembacaan berulang yang memakan kuota harian Anda.
• Lengkap: pengiriman dicoba ulang, sehingga gangguan singkat di sisi Anda tidak menghilangkan peristiwa.

3Peristiwa yang dapat Anda langgan

Ada tujuh jenis peristiwa yang dapat dilanggan, mencakup vonis spam, hukuman, dan perubahan keanggotaan. Satu pesan yang dimoderasi dapat menghasilkan lebih dari satu peristiwa — pesan spam yang berakhir dengan blokir memancarkan baik spam.detected maupun user.banned.

• spam.detected — mesin menandai sebuah pesan sebagai spam.
• message.suspicious — deteksi bayangan (mode pemantauan) dengan skor.
• user.banned — seorang anggota diblokir.
• user.kicked — seorang anggota dikeluarkan.
• user.muted — seorang anggota dibisukan.
• user.joined — seorang anggota bergabung ke grup.
• user.left — seorang anggota keluar dari grup.

4Amplop payload

Setiap pengiriman adalah amplop JSON dengan sekumpulan field tingkat atas yang kecil dan stabil serta objek data khusus-peristiwa di dalamnya. Anda dapat merutekan berdasarkan type dan waktu tanpa menguraikan detailnya sampai Anda membutuhkannya.

• id — delivery id unik; pengiriman ulang dari peristiwa yang sama memakai id yang sama, yang menjadi cara Anda mendeduplikasi.
• type — jenis peristiwa, salah satu dari tujuh di atas.
• created_at — kapan peristiwa terpicu, dalam RFC3339 UTC.
• group_id — grup tempat peristiwa itu berasal (bila berlaku).
• data — objek khusus-peristiwa: detail pesan dan vonis untuk peristiwa spam, detail anggota untuk peristiwa keanggotaan.

5Memverifikasi bahwa pengiriman benar-benar dari Telm

Setiap pengiriman ditandatangani sehingga server Anda dapat memastikan permintaan benar-benar datang dari Telm dan tidak diutak-atik selama transit. Validasi tanda tangan sebelum Anda mempercayai payload, dan tolak apa pun yang tidak cocok.

Tanda tangan adalah HMAC-SHA256 dari timestamp dan body permintaan mentah, dikunci dengan rahasia penandatanganan endpoint Anda. Untuk memverifikasi, hitung ulang HMAC atas header timestamp dan byte persis yang Anda terima, lalu bandingkan dengan header tanda tangan.

• X-Telm-Signature — tanda tangan, diformat sebagai v1 diikuti oleh HMAC-SHA256 hex dari timestamp yang digabungkan dengan body.
• X-Telm-Timestamp — timestamp unix-detik yang ditandatangani, sehingga Anda dapat menolak pengiriman yang basi atau diputar ulang.
• X-Telm-Event — jenis peristiwa, dan X-Telm-Delivery — delivery id untuk deduplikasi.
• Rahasia penandatanganan ditampilkan sekali saat Anda membuat endpoint dan dimulai dengan whsec_. Simpan dengan aman; itulah satu-satunya hal yang membuktikan sebuah pengiriman asli.

6Pengiriman yang andal dan terdeduplikasi

Pengiriman bersifat setidaknya-sekali: Telm memastikan sebuah peristiwa sampai kepada Anda, yang berarti peristiwa yang sama sesekali dapat tiba dua kali. Karena setiap pengiriman ulang memakai delivery id yang sama, Anda mendeduplikasi dengan menyimpan id yang telah Anda proses dan melewati pengulangan.

Jika endpoint Anda tidak dapat dijangkau atau mengembalikan kesalahan, pengiriman dicoba ulang sesuai jadwal tetap — kira-kira setelah satu menit, lima menit, tiga puluh menit, dua jam, dan enam jam, hingga enam upaya selama sekitar delapan setengah jam. Endpoint yang terus gagal otomatis dinonaktifkan untuk melindungi kedua sisi, dan pemiliknya diberi tahu.

• Balas dengan cepat dengan status 2xx; lakukan pekerjaan berat secara asinkron setelah mengakui.
• Deduplikasi pada delivery id — jangan pernah pada isi payload.
• Endpoint yang gagal sekitar dua puluh kali berturut-turut tanpa keberhasilan dalam jendela 72 jam akan dinonaktifkan otomatis; aktifkan kembali begitu server Anda sehat.

7Mengelola endpoint dan membaca log

Anda mendaftarkan, menyunting, dan menghapus endpoint webhook melalui API. Ketika Anda membuat satu, Anda menerima rahasia penandatanganan tepat sekali, memilih peristiwa yang akan dilanggan, dan secara opsional mencakupkannya ke grup tertentu. Panggilan uji mengirim ping yang ditandatangani sehingga Anda dapat memastikan verifikasi Anda berfungsi sebelum lalu lintas nyata dimulai.

Setiap endpoint menyimpan log pengiriman yang dapat Anda baca kembali untuk melihat apa yang dikirim, kapan, dan apakah berhasil — berguna untuk men-debug penerima tanpa menunggu peristiwa langsung berikutnya.

• Buat endpoint dan salin rahasia whsec_ segera.
• Kirim ping uji untuk memvalidasi pemeriksaan tanda tangan Anda dari ujung ke ujung.
• Cakupkan endpoint ke satu grup atau biarkan terbuka untuk semua grup yang Anda administrasi.
• Baca log pengiriman untuk memeriksa upaya terbaru dan hasilnya.

8Praktik terbaik dan kesalahan umum

Penerima yang tangguh mengikuti beberapa aturan yang mencegah masalah paling umum.

• Verifikasi tanda tangan atas byte body mentah — menguraikan ke JSON dulu lalu menyerialkan ulang dapat mengubah byte dan merusak pemeriksaan.
• Kembalikan 2xx dengan cepat dan proses kemudian; handler yang lambat menyebabkan timeout dan percobaan ulang yang tak perlu.
• Buat penanganan idempoten agar peristiwa yang dikirim ulang tidak menghitung ganda.
• Gunakan HTTPS pada URL yang dapat dijangkau publik; Telm memblokir alamat internal dan privat serta tidak mengikuti pengalihan.
• Jauhkan rahasia whsec_ dari log dan kode klien.