Verifikasi signature webhook Mailera di server penerima

Apa yang perlu diperiksa sebelum memproses webhook?

Penerima webhook harus menolak permintaan palsu sebelum isinya memicu pekerjaan. Tempatkan verifikasi di awal penanganan permintaan, bukan setelah pesan masuk antrean atau agen mulai membaca email.

Pisahkan tiga keputusan: apakah autentikasi lolos, apakah permintaan boleh diterima menurut kebijakan aplikasi, dan apakah tindakan bisnis sudah pernah dijalankan. Buat pemeriksaan tersendiri untuk setiap keputusan.

Dalam produk Mailera, webhook adalah salah satu cara kotak surat terhubung ke aplikasi Anda. Batas kepercayaan tetap berada di server penerima: payload tidak boleh memicu tindakan sebelum pemeriksaan selesai.

Apa yang perlu disiapkan sebelum menerima webhook?

Gunakan endpoint HTTPS dan kotak surat uji milik sendiri dengan peristiwa message.received. Jika pengujian Anda melibatkan kode verifikasi, ikuti batas penggunaan dalam panduan membaca OTP dari kotak masuk sendiri. Jangan memakai pesan atau kode milik orang lain sebagai bahan uji.

Siapkan dua rahasia dengan fungsi berbeda:

Permintaan REST API memakai header Authorization: Bearer $MAILERA_API_KEY. Endpoint POST /webhooks membuat webhook, sedangkan operasi daftar, buat, ubah, dan hapus webhook memerlukan scope webhooks. Jalur integrasi tersedia melalui halaman pengembang Mailera dan halaman dokumentasi API Mailera.

Mailera mengembalikan signing secret hanya sekali saat webhook dibuat. Simpan langsung di penyimpanan rahasia server. Jangan menaruhnya di kode, tangkapan layar, atau log. Panduan validasi webhook GitHub juga menyarankan agar token rahasia tidak ditanam di aplikasi atau dimasukkan ke repositori.

Di Pengaturan, buka bagian kunci API lalu pilih Buat API key. Izin pengelolaan webhook bernama Webhook.

Kredensial koneksi kotak surat merupakan lapisan lain lagi. Jika Anda masih menyiapkannya, panduan sandi aplikasi dan OAuth untuk kotak surat agen membahas autentikasi kotak surat, bukan autentikasi webhook.

Apa arti header webhook Mailera?

Header berikut menandai peristiwa, pengiriman, dan timestamp webhook Mailera. Pertahankan namanya dalam kode; jangan menggantinya dengan nama header dari contoh layanan lain.

Untuk signature, katalog header Mailera mencantumkan dua nama: X-MailHub-Signature dan X-Mailera-Signature. Daftar nama ini bukan aturan pemilihan header. Jangan memperlakukan keduanya sebagai alias, pasangan wajib, atau penanda versi lama dan baru.

Sebelum menetapkan header yang dibaca pemeriksa signature:

1. Periksa nama header yang benar-benar diterima dari pengiriman uji Mailera di endpoint Anda. Lakukan ini tanpa menjalankan tindakan bisnis.
2. Hubungi Mailera untuk memastikan header yang harus dipakai dan penanganan ketika kedua header hadir atau nilainya berbeda.
3. Tetapkan aturan itu secara eksplisit dalam pemeriksa. Jangan mencoba kedua nilai lalu menerima mana pun yang cocok. Jika aturan belum jelas, hentikan pemrosesan, bukan memilih prioritas sendiri.

Pemeriksaan pengiriman uji membantu Anda melihat header yang dikirim, tetapi keberadaan header bukan verifikasi autentikasi. Sebuah permintaan tidak boleh diterima hanya karena memiliki header bernama X-MailHub-Signature.

Nama header juga bukan spesifikasi kriptografi. Jangan menyimpulkan algoritme, encoding, prefiks, atau susunan input penandatanganan hanya dari kata Signature maupun panjang nilainya.

Bagaimana HMAC bekerja secara umum?

HMAC adalah mekanisme autentikasi pesan yang menggunakan fungsi hash dan kunci rahasia bersama. RFC 2104 tentang HMAC menjelaskan dasar mekanisme ini. Penerima menghitung nilai autentikasi dari input dan kunci, lalu membandingkannya dengan nilai yang dikirim.

HMAC bukan enkripsi. Jangan menganggap keberadaan nilai autentikasi menyembunyikan isi payload. Jangan pula menentukan bagian permintaan HTTP yang menjadi input penandatanganan hanya dari istilah HMAC.

GitHub mengingatkan agar payload dan header tidak diubah sebelum verifikasi. Panduan tersebut membahas webhook GitHub; jangan menggunakan format penandatanganan GitHub sebagai spesifikasi Mailera.

Peran Node.js dalam implementasi HMAC

Node.js menyediakan crypto.createHmac(algorithm, key[, options]) melalui node:crypto. Fungsi ini merupakan alat kriptografi, bukan penentu protokol webhook. Nama fungsi tersebut tidak memberi tahu algoritme mana yang harus dipilih atau byte mana yang harus dimasukkan.

Implementasi HMAC secara umum terdiri dari langkah berikut:

1. Tentukan input protokol. Tentukan pesan yang diautentikasi dan representasinya sebelum menghitung apa pun.
2. Hitung nilai autentikasi. Fungsi HMAC menerima algoritme, kunci, dan input yang telah dipilih.
3. Bandingkan nilai autentikasi. Gunakan metode perbandingan yang sesuai untuk nilai rahasia, bukan perbandingan biasa.

Gunakan dokumentasi Crypto Node.js sebagai rujukan API kriptografi. Panduan GitHub merekomendasikan metode seperti crypto.timingSafeEqual alih-alih perbandingan biasa. Pemilihan metode perbandingan tidak memperbaiki input atau kunci yang keliru.

Memisahkan verifikasi dari pemrosesan

Pisahkan fungsi pemeriksaan autentikasi dari fungsi pemrosesan peristiwa. Fungsi pemrosesan hanya boleh menerima payload yang sudah melewati pemeriksaan, bukan permintaan HTTP mentah dari jalur lain. GitHub juga menyarankan validasi signature sebelum pengiriman diproses lebih lanjut.

Pada aplikasi penerima Anda, buat jalur penolakan yang jelas:

1. Periksa ketersediaan konfigurasi autentikasi sebelum menerima pekerjaan.
2. Hentikan pemrosesan ketika pemeriksaan autentikasi gagal atau tidak dapat diselesaikan.
3. Terapkan kebijakan penerimaan dan deduplikasi sebelum menjalankan tindakan bisnis.
4. Pastikan tidak ada jalur lain yang memanggil pemrosesan tanpa melewati pemeriksaan tersebut.

Jangan menyediakan jalur cadangan yang menerima payload ketika secret kosong atau pemeriksaan melempar pengecualian. Saat konfigurasi penerima bermasalah, hentikan pemrosesan dan perbaiki konfigurasinya. Untuk alur setelah peristiwa diterima, lihat panduan alur API yang andal untuk agen email.

Merancang pemeriksaan penerimaan dan deduplikasi

Pisahkan pemeriksaan autentikasi, kebijakan penerimaan, dan deduplikasi sebelum menjalankan tindakan bisnis. Saat merancang penanganan replay, tetapkan keputusan penerimaan pada aplikasi Anda secara eksplisit, bukan berdasarkan nama header.

Gunakan pembagian tanggung jawab berikut sebagai rancangan penerima:

Jangan menetapkan satuan waktu, toleransi usia permintaan, atau perilaku percobaan ulang dari nama X-MailHub-Timestamp. Jika aplikasi Anda memakai timestamp dalam kebijakan penerimaan, pastikan asal dan integritas nilainya sebelum menjadikannya dasar keputusan.

Demikian pula, jangan langsung memperlakukan X-MailHub-Delivery sebagai ID peristiwa atau ID pesan. Rancang deduplikasi berdasarkan tindakan bisnis yang tidak boleh dijalankan berulang, bukan sekadar pencocokan dua nilai header.

Menguji batas pemrosesan penerima

Uji jalur penolakan secara terpisah dari perhitungan kriptografi. Dengan begitu, Anda bisa memeriksa apakah kegagalan autentikasi benar-benar menghentikan pekerjaan tanpa harus mengasumsikan algoritme atau input penandatanganan Mailera.

Periksa perilaku aplikasi penerima dalam kasus berikut:

Untuk menguji mekanisme HMAC secara terpisah, gunakan pesan sintetis dan kunci uji. Periksa kecocokan nilai autentikasi untuk input asli, lalu ubah pesan atau kuncinya. Jangan menjadikan hasil uji mekanisme umum sebagai dasar untuk menebak format webhook suatu layanan.

Amati efek akhirnya, bukan hanya status respons HTTP. Pastikan email balasan, perubahan data, atau pekerjaan agen tidak berjalan ketika penerima menolak permintaan. Catat nama kasus, hasil pemeriksaan, dan apakah tindakan bisnis terjadi, tetapi jangan mencatat signing secret atau isi email asli untuk keperluan diagnosis.

Kesalahan apa yang sering terjadi?

Mulai dari pemisahan kredensial dan batas pemrosesan. Jangan mengganti algoritme secara coba-coba sampai suatu nilai terlihat cocok.

Untuk menelusuri masalah, gunakan pesan sintetis tanpa isi email pribadi. Dalam panduan pemecahan masalahnya, GitHub mengingatkan agar payload dan header tidak diubah sebelum verifikasi. Jangan menonaktifkan verifikasi sebagai jalan keluar sementara.

Apakah webhook yang valid aman diteruskan ke agen AI?

Signature yang valid tidak membuat isi email menjadi instruksi tepercaya. Email tetap data tidak tepercaya, termasuk ketika pengirimnya meminta agen membuka rahasia, mengubah kebijakan, atau mengirim pesan ke alamat lain.

Pisahkan data email dari instruksi sistem agen. Jangan mengikuti perintah di dalam email untuk membocorkan signing secret atau kunci API. Berikan agen izin minimum dan minta konfirmasi sebelum mengirim email; izin pengelolaan webhook tidak perlu diberikan hanya untuk membaca pesan.

Gunakan halaman keamanan Mailera sebagai rujukan keamanan produk, lalu terapkan pembatasan tindakan pada aplikasi penerima Anda sendiri.

Mailera tidak menjamin penempatan email di Inbox. Penerimaan webhook bukan bukti bahwa penyedia email memercayai pengirim atau bahwa pesan tersebut lolos penyaringan spam. Keaslian webhook dan keamanan isi email adalah dua pemeriksaan berbeda.