Telm boleh menolak acara moderasi ke pelayan anda secara masa nyata. Anda mendaftarkan satu titik akhir, memilih acara mana untuk diterima, dan Telm menghantar POST yang ditandatangani untuk setiap satu. Setiap penghantaran membawa tandatangan HMAC-SHA256 yang anda sahkan dengan rahsia titik akhir anda. Penghantaran yang gagal dicuba semula mengikut jadual; titik akhir yang kekal tidak boleh dicapai dinyahdayakan secara automatik.
1Sampul acara
Setiap webhook ialah POST HTTP dengan badan JSON dalam sampul yang sama. Sampul mempunyai id (pengecam penghantaran unik untuk penyahduaan), type (nama acara), cap masa created_at, group_id yang acara itu tergolong, dan objek data yang bentuknya bergantung pada jenis acara.
id adalah deterministik untuk acara sebenar, jadi jika acara yang sama dihantar dua kali — contohnya selepas cubaan semula — anda menerima id yang sama kedua-dua kali. Gunakan pengepala X-Telm-Delivery (yang mencerminkan id ini) sebagai kunci idempoten supaya pengendali anda memproses setiap acara hanya sekali.
- Medan sampul: id, type, created_at, group_id, data.
- type ialah salah satu nama acara dari katalog di bawah.
- data membawa medan khusus acara.
- Gunakan id (dan pengepala X-Telm-Delivery) untuk menyahduakan cubaan semula.
2Katalog acara
Anda melanggan titik akhir kepada mana-mana subset katalog. spam.detected diaktifkan apabila enjin menandakan mesej sebagai spam. message.suspicious diaktifkan dalam mod pemantauan, apabila enjin akan bertindak tetapi hanya mencetak skor bayang mesej itu. Acara ahli meliputi orang yang masuk, keluar, dan dihukum.
Acara ping adalah istimewa: ia bukan sebahagian daripada katalog boleh langgan dan hanya dihantar apabila anda mencetuskan penghantaran ujian untuk titik akhir, supaya anda boleh mengesahkan penerima dan semakan tandatangan anda berfungsi hujung ke hujung.
- spam.detected — mesej diklasifikasikan sebagai spam.
- message.suspicious — pengesanan bayang (mod pemantauan).
- user.banned, user.kicked, user.muted — tindakan moderasi telah dikenakan.
- user.joined, user.left — ahli masuk atau keluar dari kumpulan.
- ping — acara ujian manual, tidak pernah diaktifkan oleh aktiviti sebenar.
3Medan muatan setiap acara
Untuk spam.detected dan message.suspicious, objek data membawa message_id, user_id, username, teks mesej (dipangkas untuk mesej yang sangat panjang), tindakan yang diambil, satu category, satu reason, bahasa yang dikesan, dan skor keyakinan. message.suspicious tambahan membawa skor bayang.
Untuk acara ahli (user.joined, user.left, user.banned, user.kicked, user.muted), objek data membawa user_id, username, first_name, message_id pilihan, dan reason di mana satu terpakai. Satu acara asas boleh menghasilkan lebih daripada satu webhook — mesej spam yang mencetuskan larangan dihantar sebagai kedua-dua spam.detected dan user.banned.
- Acara spam: message_id, user_id, username, text, action, category, reason, language, confidence (ditambah score untuk message.suspicious).
- Acara ahli: user_id, username, first_name, message_id, reason.
- Satu kejadian mungkin memancarkan beberapa acara; korelasikannya mengikut user_id dan group_id.
4Mengesahkan tandatangan HMAC
Setiap penghantaran ditandatangani supaya anda boleh pasti ia benar-benar datang dari Telm dan tidak diusik. Anda mendapat rahsia titik akhir (ia bermula dengan whsec_) sekali, apabila anda mencipta titik akhir. Simpannya dan gunakannya untuk mengesahkan setiap permintaan masuk.
Untuk mengesahkan, ambil nilai pengepala X-Telm-Timestamp, tambah satu titik, kemudian tambah badan permintaan mentah yang tepat, dan kira HMAC-SHA256 bagi rentetan itu menggunakan rahsia titik akhir anda sebagai kunci. Enkod-hex hasilnya dan awalinya dengan v1= — ia mesti sama dengan pengepala X-Telm-Signature. Bandingkan dengan perbandingan masa malar, dan tolak permintaan itu jika cap masa lebih tua daripada beberapa minit (lima ialah titik potong yang baik) untuk menyekat main semula.
- X-Telm-Event — jenis acara.
- X-Telm-Delivery — id penghantaran (kunci idempoten).
- X-Telm-Timestamp — saat unix, ditandatangani untuk mengelakkan main semula.
- X-Telm-Signature — v1= ditambah hex HMAC-SHA256 bagi cap masa, satu titik, dan badan mentah.
5Penghantaran, cubaan semula dan nyahdaya automatik
Penghantaran dikira berjaya hanya jika titik akhir anda membalas dengan status 2xx. Apa sahaja yang lain — kod bukan 2xx, masa tamat, atau ralat sambungan — dianggap sebagai kegagalan dan dicuba semula mengikut jadual tetap: serta-merta, kemudian selepas 1 minit, 5 minit, 30 minit, 2 jam dan 6 jam, untuk enam percubaan menjangkau kira-kira lapan setengah jam sebelum penghantaran ditutup sebagai gagal.
Jika titik akhir terus gagal — sekurang-kurangnya dua puluh kegagalan berturut-turut tanpa penghantaran berjaya selama tiga hari — Telm secara automatik menyahdayakannya supaya ia berhenti menghantar ke URL mati. Anda boleh mendayakannya semula dari papan pemuka sebaik penerima anda sihat semula.
- Berjaya = HTTP 2xx. Balas pantas (dalam kira-kira sepuluh saat) dan lakukan kerja berat secara tak segerak.
- Jadual cubaan semula: serta-merta, +1m, +5m, +30m, +2h, +6h (enam percubaan).
- Dinyahdaya automatik selepas 20 kegagalan berturut-turut tanpa kejayaan dalam 72 jam.
- Mendaftarkan webhook memerlukan pelan Pro atau lebih tinggi.