Layanan pembayaran Square mengirimkan notifikasi otomatis (webhook) ke sistem mitra setiap kali terjadi transaksi, pengembalian dana, atau sengketa. Mekanisme keamanan yang digunakan bergantung pada tanda tangan digital di header permintaan. Namun, banyak pengembang aplikasi mendapati proses verifikasi mereka gagal secara misterius meski kode terlihat benar.
Akar masalahnya terletak pada cara Square membentuk pesan yang dienkripsi. Tanda tangan HMAC-SHA256 tidak hanya dihitung dari isi permintaan (body), melainkan juga dari URL notifikasi yang didaftarkan. Jika URL tersebut tidak sama persis, termasuk perbedaan satu karakter garis miring di akhir, validasi akan gagal total.
Square menyertakan header `x-square-hmacsha256-signature` pada setiap webhook yang dikirimkan. Berdasarkan dokumentasi resmi Square, nilai tersebut merupakan hasil HMAC-SHA-256 yang dibangun dari tiga elemen: kunci tanda tangan spesifik untuk langganan webhook, URL notifikasi yang dikonfigurasi, serta body mentah permintaan.
Pesan yang diproses melalui algoritma HMAC adalah gabungan URL notifikasi diikuti body mentah secara berurutan, lalu dienkode dengan Base64. Pengembang harus menghitung nilai yang sama dan membandingkannya dengan header yang diterima. Skema ini dirancang untuk memastikan bahwa notifikasi benar-benar berasal dari Square dan tidak diubah selama transmisi.
Kebijakan menggabungkan URL ke dalam pesan kriptografis merupakan langkah keamanan ganda. Sayangnya, hal ini menjadi jebakan terselubung bagi mereka yang membangun ulang URL dari variabel server seperti `req.protocol` atau `req.headers.host`. Di balik load balancer yang menghentikan TLS, aplikasi bisa menerima protokol `http` alih-alih `https`, sehingga string URL tidak cocok dengan yang tersimpan di dashboard Square.
Bagi ekosistem teknologi di Indonesia, pola kegagalan ini sangat relevan. Meskipun Square memiliki pangsa pasar terbatas di dalam negeri dibandingkan penyedia lokal seperti Midtrans, Xendit, atau DOKU, prinsip verifikasi webhook bersifat universal. Banyak startup lokal juga mengandalkan integrasi webhook untuk sinkronisasi status pembayaran secara real-time.
Kesalahan memverifikasi body yang sudah di-parse ulang ke format JSON merupakan jebakan kedua yang mematikan. HMAC menandatangani byte, bukan objek. Jika kerangka kerja (framework) seperti Express mem-parsing JSON lalu pengembang membangun ulang string untuk verifikasi, urutan kunci, spasi, dan format angka akan bergeser. Akibatnya, tanda tangan tidak akan pernah cocok.
Dampak dari kegagalan verifikasi ini bukan sekadar error teknis biasa. Square akan mencoba mengirim ulang notifikasi yang gagal untuk beberapa waktu. Namun, jika server terus menolak, langganan webhook tersebut akan dinonaktifkan. Peristiwa yang hilang justru yang paling krusial: penyelesaian pembayaran, pengembalian dana, dan sengketa, yang berujung pada ketidakselarasan data keuangan.
Panduan integrasi Square secara tegas menganjurkan penggunaan perbandingan waktu-konstan (constant-time compare) seperti `crypto.timingSafeEqual` daripada operator `===`. Perbandingan string biasa akan berhenti lebih awal saat menemukan byte pertama yang berbeda, membocorkan informasi seberapa banyak tanda tangan yang sudah benar kepada penyerang potensial.
Selain itu, pengembang harus segera meninggalkan header warisan `x-square-signature` yang menggunakan HMAC-SHA1. Skema lama ini sedang digulung secara bertahap karena SHA1 bukanlah algoritma hash yang aman untuk melindungi event pembayaran. Migrasi ke `x-square-hmacsha256-signature` adalah kewajiban demi menjaga integritas sistem.
Ke depannya, praktik keamanan webhook akan semakin menekankan penggunaan body mentah dan konstanta URL statis per lingkungan (sandbox versus produksi). Pengembang tidak boleh lagi menyimpulkan URL dari permintaan masuk secara dinamis. Memisahkan lingkungan sandbox dan produksi dengan kunci berbeda juga wajib agar verifikasi tidak tertukar.
Tren serupa juga terlihat pada platform lain seperti Stripe, Paddle, hingga Twilio yang mengikat tanda tangan ke URL permintaan. Kesadaran akan arsitektur verifikasi ini harus menjadi standar baku bagi engineer Indonesia. Kehilangan satu notifikasi transaksi bisa berarti kerugian langsung bagi merchant yang mengandalkan otomasi penuh.