Webhook — peristiwa moderasi masa nyata dalam sistem anda

1Apa yang dilakukan oleh webhook

Daripada meninjau API, anda mendaftar URL dan Telm menghantar HTTP POST yang ditandatangani kepadanya setiap kali sesuatu berlaku dalam kumpulan anda. Beginilah anda mendapat peristiwa moderasi ke dalam sistem anda sendiri — papan pemuka, gudang data, saluran amaran — secara masa nyata.

Anda menguruskan titik akhir webhook melalui API: daftar URL, pilih peristiwa mana yang hendak dilanggan, secara pilihan hadkan ia kepada kumpulan tertentu, hantar ping ujian, dan baca log penghantaran terkini.

2Mengapa menolak mengalahkan tinjauan

Anda boleh memanggil titik akhir jurnal mengikut pemasa untuk mencari peristiwa baharu, tetapi itu menambah kependaman, membelanjakan kuota, dan boleh terlepas saat tepat sesuatu berlaku. Webhook membalikkan model: Telm memberitahu anda sebaik sahaja peristiwa dicetuskan, jadi sistem anda bertindak balas dalam beberapa saat.

Penggunaan biasa termasuk mencerminkan pengharaman ke dalam alat pentadbir anda sendiri, memberi amaran kepada saluran pasukan apabila serbuan dikesan, menstrimkan pengesanan ke dalam analitik, atau mencetuskan aliran kerja apabila ahli menyertai atau meninggalkan.

• Masa nyata: anda mengetahui tentang peristiwa apabila ia berlaku, bukan pada tinjauan seterusnya.
• Cekap: tiada bacaan berulang yang menghakis kuota harian anda.
• Lengkap: penghantaran dicuba semula, jadi gangguan singkat di pihak anda tidak kehilangan peristiwa.

3Peristiwa yang boleh anda langgan

Terdapat tujuh jenis peristiwa yang boleh dilanggan, meliputi keputusan spam, hukuman dan perubahan keahlian. Satu mesej yang dimoderasi boleh menghasilkan lebih daripada satu peristiwa — mesej spam yang berakhir dengan pengharaman memancarkan kedua-dua spam.detected dan user.banned.

• spam.detected — enjin menandai mesej sebagai spam.
• message.suspicious — pengesanan bayangan (mod pemantauan) dengan skor.
• user.banned — ahli diharamkan.
• user.kicked — ahli dibuang.
• user.muted — ahli dibisukan.
• user.joined — ahli menyertai kumpulan.
• user.left — ahli meninggalkan kumpulan.

4Sampul muatan

Setiap penghantaran ialah sampul JSON dengan satu set medan peringkat atas yang kecil dan stabil serta objek data khusus peristiwa di dalamnya. Anda boleh menghala berdasarkan jenis dan masa tanpa menghuraikan butiran sehingga anda memerlukannya.

• id — id penghantaran yang unik; penghantaran semula peristiwa yang sama menggunakan semula id yang sama, iaitu cara anda menyahduplikat.
• type — jenis peristiwa, satu daripada tujuh di atas.
• created_at — bila peristiwa dicetuskan, dalam RFC3339 UTC.
• group_id — kumpulan yang peristiwa itu tergolong (apabila berkenaan).
• data — objek khusus peristiwa: butiran mesej dan keputusan untuk peristiwa spam, butiran ahli untuk peristiwa keahlian.

5Mengesahkan penghantaran benar-benar daripada Telm

Setiap penghantaran ditandatangani supaya pelayan anda boleh mengesahkan permintaan itu benar-benar datang daripada Telm dan tidak diusik semasa transit. Sahkan tandatangan sebelum anda mempercayai muatan, dan tolak apa-apa yang tidak sepadan.

Tandatangan ialah HMAC-SHA256 bagi cap masa dan badan permintaan mentah, dikunci dengan rahsia penandatanganan titik akhir anda. Untuk mengesahkan, kira semula HMAC bagi pengepala cap masa dan bait tepat yang anda terima, dan bandingkannya dengan pengepala tandatangan.

• X-Telm-Signature — tandatangan, diformat sebagai v1 diikuti oleh hex HMAC-SHA256 bagi cap masa yang disambung kepada badan.
• X-Telm-Timestamp — cap masa unix-saat yang ditandatangani, jadi anda boleh menolak penghantaran yang basi atau dimainkan semula.
• X-Telm-Event — jenis peristiwa, dan X-Telm-Delivery — id penghantaran untuk penyahduplikatan.
• Rahsia penandatanganan ditunjukkan sekali sahaja apabila anda mencipta titik akhir dan bermula dengan whsec_. Simpannya dengan selamat; ia satu-satunya perkara yang membuktikan penghantaran itu tulen.

6Penghantaran yang boleh dipercayai dan dinyahduplikat

Penghantaran adalah sekurang-kurangnya sekali: Telm memastikan peristiwa sampai kepada anda, yang bermakna peristiwa yang sama kadangkala boleh tiba dua kali. Kerana setiap penghantaran semula menggunakan semula id penghantaran yang sama, anda menyahduplikat dengan menyimpan id yang telah anda proses dan melangkau pengulangan.

Jika titik akhir anda tidak dapat dihubungi atau memulangkan ralat, penghantaran dicuba semula mengikut jadual tetap — kira-kira selepas satu minit, lima minit, tiga puluh minit, dua jam dan enam jam, sehingga enam percubaan dalam kira-kira lapan setengah jam. Titik akhir yang terus gagal dilumpuhkan secara automatik untuk melindungi kedua-dua pihak, dan pemilik diberitahu.

• Balas dengan pantas dengan status 2xx; lakukan kerja berat secara tak segerak selepas mengakui.
• Nyahduplikat berdasarkan id penghantaran — jangan sekali-kali berdasarkan kandungan muatan.
• Titik akhir yang gagal kira-kira dua puluh kali berturut-turut tanpa kejayaan dalam tetingkap 72 jam dilumpuhkan secara automatik; dayakan semula setelah pelayan anda sihat.

7Menguruskan titik akhir dan membaca log

Anda mendaftar, menyunting dan mengeluarkan titik akhir webhook melalui API. Apabila anda mencipta satu, anda menerima rahsia penandatanganan sekali sahaja, memilih peristiwa untuk dilanggan, dan secara pilihan menskopkannya kepada kumpulan tertentu. Panggilan ujian menghantar ping yang ditandatangani supaya anda boleh mengesahkan pengesahan anda berfungsi sebelum trafik sebenar bermula.

Setiap titik akhir menyimpan log penghantaran yang boleh anda baca semula untuk melihat apa yang dihantar, bila, dan sama ada ia berjaya — berguna untuk menyahpepijat penerima tanpa menunggu peristiwa langsung seterusnya.

• Cipta titik akhir dan salin rahsia whsec_ serta-merta.
• Hantar ping ujian untuk mengesahkan semakan tandatangan anda dari hujung ke hujung.
• Skopkan titik akhir kepada satu kumpulan atau biarkan ia terbuka kepada semua kumpulan yang anda tadbir.
• Baca log penghantaran untuk memeriksa percubaan terkini dan hasilnya.

8Amalan terbaik dan kesilapan biasa

Penerima yang teguh mengikuti beberapa peraturan yang menghalang masalah paling biasa.

• Sahkan tandatangan berdasarkan bait badan mentah — menghuraikannya kepada JSON dahulu kemudian menyusunnya semula boleh menukar bait tersebut dan merosakkan semakan.
• Pulangkan 2xx dengan pantas dan proses kemudian; pengendali yang perlahan menyebabkan tamat masa dan cubaan semula yang tidak perlu.
• Jadikan pengendalian idempoten supaya peristiwa yang dihantar semula tidak dikira dua kali.
• Gunakan HTTPS pada URL yang boleh dihubungi secara awam; Telm menyekat alamat dalaman dan peribadi serta tidak mengikuti pengalihan.
• Simpan rahsia whsec_ jauh daripada log dan kod klien.