Polling status adalah cara paling sederhana untuk mendapatkan kode: kirim permintaan, lihat respons, dan jika masih kosong, ulangi beberapa detik kemudian. Kesederhanaan ini menipu: setiap permintaan tambahan membebani batas API, sementara keterlambatannya tetap tidak pasti, karena kode bisa muncul tepat setelah pengecekan dan baru diambil pada siklus berikutnya. Webhook bekerja berbeda: server sendiri memberi tahu begitu suatu peristiwa terjadi. Berikut yang didapat dari peralihan ke webhook dalam praktik, apa yang perlu disiapkan di sisi Anda, cara membedakan panggilan asli dari yang palsu, dan kapan polling tetap tidak bisa dihindari.
Push versus polling: manfaat webhook
Pada polling, klien memanggil endpoint status setiap beberapa detik, dan sebelum kode diterima hampir semua respons berarti "belum ada yang baru". Dengan belasan aktivasi paralel, jumlahnya sudah ratusan panggilan sia-sia per menit yang menekan batas API, tetapi tidak menghilangkan jeda antara saat kode muncul di server dan saat aplikasi mengetahuinya. Apa itu kode OTP dijelaskan dalam artikel apa itu kode OTP.
Webhook membalik skemanya: server pengirim sendiri mengirim permintaan ke alamat webhook begitu peristiwa siap. Keterlambatan menyusut menjadi waktu pengiriman satu permintaan HTTP, dan jumlah panggilan ke API turun menjadi satu per aktivasi, bukan puluhan kali polling sambil menunggu hasil.
Apa yang perlu disiapkan di sisi Anda
Syarat pertama adalah alamat webhook yang dapat diakses publik. Penerima harus bisa dijangkau dari luar melalui HTTPS: dengan domain atau IP publik, tanpa alamat jaringan lokal dan tanpa proxy di antara pengirim dan server. Jika alamat tidak dapat di-resolve dari internet, peristiwa tidak punya tujuan pengiriman — pengirim akan mencatat kesalahan koneksi, bukan sekadar sepi di sisinya. Penyebab penerima menjadi tidak dapat dijangkau dibahas dalam artikel tentang putusnya panggilan balik.
Syarat kedua adalah kecepatan respons. Handler webhook harus menerima isi permintaan dan langsung mengembalikan kode 2xx, tanpa menunggu logika bisnis — mengurai teks, mencari kode dengan regex, menulis ke basis data. Pekerjaan itu dipindahkan ke antrean dan dijalankan oleh proses terpisah. Jika pemrosesan dilakukan sinkron sebelum menjawab, basis data atau layanan pihak ketiga yang melambat akan berujung timeout, dan pengirim menganggap pengiriman gagal, padahal peristiwanya sebenarnya sudah sampai.
Tanda tangan permintaan: cara memastikan webhook asli
Alamat webhook publik terlihat oleh siapa pun yang menemukannya atau mengintipnya dari lalu lintas yang disadap. Tanpa pemeriksaan keaslian, endpoint akan menerima isi apa pun dengan konten sembarang — cukup mengirim permintaan POST dengan "kode" karangan, dan handler akan menelannya sebagai peristiwa sungguhan.
Tanda tangan menutup celah ini: pengirim meng-hash isi permintaan dengan kunci rahasia dan menaruh hasilnya di header, lalu penerima menghitung ulang hash dengan kunci yang sama dan membandingkan nilainya. Kecocokan membuktikan keaslian sumber webhook sekaligus bahwa isinya tidak berubah di perjalanan. Kunci hanya disimpan di server dan tidak masuk ke kode klien; jika dicurigai bocor, kunci dirotasi di dasbor akun, dengan memperbarui pemeriksaan di sisi Anda secara bersamaan.
Pengiriman ulang webhook itu normal, bukan gangguan
Pengirim tidak bisa sepenuhnya yakin bahwa kode 2xx berarti "peristiwa tersimpan", dan bukan "server menjawab, tetapi pemrosesan gagal sedetik kemudian". Karena itu sebagian besar sistem mengulang pengiriman webhook sesuai jadwal: beberapa detik kemudian, lalu semenit kemudian, dan seterusnya beberapa kali, sampai menerima konfirmasi atau kehabisan batas percobaan. Akibatnya, kode yang sama dengan pengenal peristiwa yang sama bisa datang dua kali, bahkan tiga kali.
Handler harus idempoten: sebelum menyimpan, periksa apakah kode dengan pengenal aktivasi atau peristiwa tersebut sudah tersimpan, dan pada pengiriman ulang cukup balas 200 tanpa membuat data baru. Percobaan ulang dari pengirim mirip dengan cara mengulang permintaan Anda sendiri ke API pihak lain — prinsip umumnya dibahas dalam artikel kesalahan API: cara menangani dan mengulang permintaan. Jika penerima tidak tersedia selama seluruh jendela pengiriman ulang, peristiwa tidak akan hilang hanya dengan satu syarat — pengirim memiliki antrean peristiwa yang belum terkirim, sehingga yang terlewat bisa diambil secara manual lewat permintaan status terpisah.
Kapan polling masih tepat
Jika tugas tidak punya alamat publik yang tetap — lingkungan uji tanpa domain, skrip sekali pakai di mesin di balik NAT, atau uji coba singkat yang dimatikan dalam sehari — membuat webhook untuknya tidak masuk akal. Polling dengan interval beberapa detik menyelesaikan tugas sekali atau jarang tanpa infrastruktur penerima dan tanda tangan.
Kasus kedua adalah permintaan yang benar-benar tunggal: satu kode untuk satu aktivasi, tanpa arus peristiwa, di mana keuntungan webhook tidak sepadan dengan penyiapan alamat publik dan antrean pemrosesan. Pada penerimaan kode yang rutin atau paralel, perbandingannya berbalik: polling mulai menghabiskan batas API lebih cepat daripada waktu integrasi yang dihemat.
Pertanyaan yang Sering Diajukan
Bolehkah satu alamat webhook yang sama dipakai untuk beberapa layanan?
Secara teknis boleh, selama handler membedakan peristiwa berdasarkan kolom pengenal layanan atau aktivasi di isi permintaan. Lebih praktis jika sumber dipisahkan ke path berbeda pada satu domain — dengan begitu log lebih mudah dibaca dan tanda tangan satu sumber bisa diperbarui tanpa menyentuh yang lain.
Apa yang harus dilakukan jika penyedia tidak mendukung pengiriman ulang?
Siapkan polling status paralel sebagai pengaman kalau penerima tidak tersedia saat satu-satunya percobaan push. Lakukan polling dengan jarang — sekali setiap beberapa menit: itu cukup untuk mengambil peristiwa yang terlewat, tanpa menjadikan polling sebagai saluran utama.
Bagaimana memastikan tanda tangan berfungsi dengan benar sebelum rilis ke produksi?
Kirim peristiwa uji dengan isi yang sengaja dirusak atau header tanda tangan yang salah, lalu pastikan handler menolaknya sebelum menulis ke basis data. Setelah itu ulangi dengan tanda tangan yang benar dan pengenal peristiwa yang sama dua kali berturut-turut — panggilan kedua harus mengembalikan 200 tanpa membuat data baru.
Format peristiwa, header tanda tangan, struktur isi permintaan, dan parameter percobaan ulang untuk penerimaan kode lewat webhook dijelaskan dalam dokumentasi API.