Webhook digunakan untuk mengirimkan event secara otomatis dari layanan WhatsApp API ke server aplikasi. Event tersebut bisa berupa pesan masuk, perubahan status pesan, atau perubahan koneksi device, bergantung pada event yang didukung layanan.
Masalah muncul ketika server penerima sedang mati, lambat, atau tidak dapat dijangkau. Pengiriman webhook bisa gagal karena koneksi terputus, waktu respons habis, atau server mengembalikan status HTTP yang dianggap gagal oleh layanan pengirim.
Salah satu cara menangani kondisi ini adalah dengan retry webhook, yaitu mencoba mengirimkan kembali event yang gagal diterima. Namun, retry saja tidak cukup. Sistem juga perlu mencegah event yang sama diproses berulang kali dan memastikan data penting tidak hilang.

Apa Itu Retry Webhook?
Retry webhook adalah proses pengiriman ulang event ketika percobaan sebelumnya tidak berhasil diselesaikan. Proses ini membantu mengatasi gangguan sementara, seperti server tidak aktif, koneksi jaringan bermasalah, atau respons yang terlalu lambat.
Contohnya, sebuah sistem menerima notifikasi pesan WhatsApp melalui webhook. Ketika server sedang mengalami gangguan, endpoint tidak memberikan respons yang sesuai. Layanan pengirim mungkin mencoba mengirimkan event tersebut kembali sesuai kebijakan retry yang berlaku.
Perlu diperhatikan bahwa kebijakan retry berbeda-beda pada setiap layanan. Jumlah percobaan, jeda antarpercobaan, batas waktu, dan jenis respons yang memicu retry harus diperiksa pada dokumentasi penyedia webhook. Jangan menganggap setiap layanan otomatis mencoba ulang dengan cara yang sama.
Penyebab Webhook Gagal Mendapatkan Respons
Sebelum mengatur retry, periksa penyebab kegagalan pengiriman webhook. Beberapa masalah berikut sering terjadi.
1. Server penerima tidak aktif
Server aplikasi mengalami restart, proses backend berhenti, atau layanan web tidak berjalan. Akibatnya, endpoint webhook tidak dapat menerima permintaan.
2. Waktu respons terlalu lama
Endpoint menjalankan proses berat sebelum memberikan respons, misalnya mengolah pesan, memperbarui banyak data, atau memanggil layanan eksternal.
Jika proses tersebut melebihi batas waktu yang ditentukan pengirim, pengiriman dapat dianggap gagal meskipun aplikasi akhirnya selesai memproses event.
3. Endpoint tidak dapat dijangkau
Alamat webhook salah, konfigurasi DNS bermasalah, sertifikat TLS tidak valid, atau firewall memblokir koneksi dari layanan pengirim.
4. Server mengembalikan status HTTP yang tidak sesuai
Endpoint dapat mengembalikan status seperti 400, 401, 403, 404, atau 500. Arti setiap status berbeda, tetapi respons tersebut dapat menandakan adanya kesalahan konfigurasi, autentikasi, alamat endpoint, atau proses aplikasi.
Apakah status tertentu memicu retry bergantung pada kebijakan layanan pengirim. Karena itu, periksa status HTTP dan dokumentasi penyedia sebelum menentukan tindakan perbaikan.
5. Proses aplikasi gagal setelah event diterima
Server mungkin berhasil menerima permintaan webhook, tetapi gagal menyimpan data atau menjalankan proses berikutnya. Kondisi ini berbeda dari kegagalan pengiriman karena endpoint tidak merespons.
Jika event sudah diterima tetapi pemrosesan internal gagal, aplikasi perlu memiliki mekanisme retry untuk proses internalnya sendiri.
Cara Menangani Retry Webhook Saat Server Tidak Merespons
Penanganan retry sebaiknya mencakup penerimaan event, penyimpanan data, pemrosesan, dan pemantauan kegagalan.
1. Pastikan endpoint webhook dapat diakses
Periksa kembali alamat endpoint yang terdaftar pada konfigurasi webhook. Pastikan alamat tersebut benar, menggunakan protokol HTTPS jika diwajibkan, dan dapat dijangkau dari luar jaringan server.
Periksa beberapa hal berikut:
- Proses backend dan web server berjalan normal.
- DNS mengarah ke server yang benar.
- Sertifikat TLS masih valid.
- Firewall tidak memblokir permintaan yang diperlukan.
- Endpoint menerima metode HTTP yang digunakan layanan pengirim.
- Aplikasi dapat membaca body permintaan sesuai format yang dikirim.
Jika endpoint tidak dapat diakses, memperbaiki proses retry saja tidak akan menyelesaikan akar masalah.
2. Berikan respons setelah event berhasil diterima dengan aman
Endpoint webhook sebaiknya merespons dengan cepat. Hindari menjalankan seluruh proses bisnis sebelum mengirimkan respons kepada pengirim.
Pola yang umum digunakan adalah:
- Menerima permintaan webhook.
- Memvalidasi permintaan sesuai kebutuhan keamanan.
- Menyimpan event ke database atau antrean pesan secara persisten.
- Mengembalikan respons HTTP
2xxsetelah penyimpanan berhasil. - Memproses event melalui worker terpisah.
Dengan pola ini, endpoint tidak harus menunggu seluruh proses bisnis selesai.
Jangan langsung mengembalikan status 2xx sebelum event tersimpan dengan aman. Jika server mengaku berhasil menerima event tetapi data belum tercatat, gangguan berikutnya dapat menyebabkan event hilang tanpa kesempatan pengiriman ulang.
Jika penyimpanan gagal, tentukan respons dan prosedur pemulihan berdasarkan kebijakan retry layanan pengirim.
3. Simpan event ke antrean pemrosesan
Antrean pesan membantu memisahkan penerimaan webhook dari proses bisnis yang membutuhkan waktu lebih lama.
Sebagai contoh, saat notifikasi pesan WhatsApp diterima, endpoint menyimpan event ke antrean. Worker kemudian mengambil event tersebut untuk memperbarui database, menjalankan otomatisasi, atau meneruskan informasi ke sistem lain.
Jika worker mengalami gangguan, event yang belum selesai diproses dapat tetap berada di antrean selama sistem antrean dan konfigurasi penyimpanannya mendukung hal tersebut.
Pastikan antrean menggunakan penyimpanan yang sesuai kebutuhan agar event tidak hilang ketika proses aplikasi atau server berhenti.
4. Cegah event yang sama diproses berulang kali
Retry dapat menyebabkan satu event diterima lebih dari satu kali. Hal ini tidak selalu berarti ada kesalahan pada pengirim. Pengiriman ulang dapat terjadi ketika respons sebelumnya tidak sampai atau tidak diterima sesuai harapan, meskipun aplikasi sudah mulai memproses event.
Untuk mengatasinya, terapkan idempotensi, yaitu memastikan pemrosesan event yang sama tidak menghasilkan efek bisnis berulang.
Caranya:
- Gunakan ID event atau ID pesan yang stabil jika tersedia pada payload.
- Simpan identitas event yang sudah diproses di database.
- Periksa identitas tersebut sebelum menjalankan proses bisnis.
- Gunakan transaksi database atau batasan unik agar dua permintaan bersamaan tidak memproses event yang sama.
- Jika payload tidak menyediakan ID yang stabil, tentukan kunci deduplikasi dari kombinasi data yang benar-benar tersedia dan cukup unik.
Contohnya, sistem menerima event yang sama dua kali. Event pertama memperbarui status pesanan. Ketika event kedua datang, sistem mengenali bahwa event tersebut sudah diproses sehingga pembaruan tidak dijalankan kembali.
Untuk proses yang melibatkan layanan eksternal, seperti mengirim pesan balasan, pastikan tindakan tersebut juga memiliki perlindungan terhadap duplikasi. Pemeriksaan database saja belum tentu mencegah dua pengiriman terjadi secara bersamaan.
5. Terapkan retry untuk proses internal yang gagal
Retry dari pengirim webhook berbeda dengan retry pemrosesan internal.
Retry dari pengirim bertujuan mengirimkan kembali event ke endpoint. Sementara itu, retry internal dilakukan ketika event sudah tersimpan, tetapi worker gagal menyelesaikan tugasnya.
Untuk retry internal, sistem dapat menerapkan aturan seperti:
- Mencatat jumlah percobaan.
- Memberikan jeda sebelum percobaan berikutnya.
- Memperpanjang jeda secara bertahap jika kegagalan terus terjadi.
- Menentukan batas percobaan.
- Memisahkan kegagalan sementara dari kegagalan permanen.
- Memindahkan event yang terus gagal ke penyimpanan khusus untuk diperiksa.
Contoh kegagalan sementara adalah layanan database tidak dapat dijangkau selama beberapa saat. Sementara itu, data yang tidak valid mungkin membutuhkan perbaikan sebelum bisa diproses kembali.
Jangan menjalankan retry tanpa batas dan tanpa jeda. Cara tersebut dapat menambah beban server yang sedang bermasalah.
6. Catat log setiap kegagalan
Log membantu menentukan apakah masalah terjadi saat pengiriman, penerimaan, penyimpanan, atau pemrosesan event.
Informasi yang sebaiknya dicatat meliputi:
- Waktu permintaan diterima.
- Identitas event atau pesan jika tersedia.
- Status HTTP yang dikembalikan.
- Durasi respons endpoint.
- Hasil penyimpanan event.
- Jumlah percobaan pemrosesan internal.
- Pesan kesalahan dan hasil akhir pemrosesan.
Hindari mencatat API key, token autentikasi, atau seluruh isi pesan yang bersifat sensitif tanpa kebutuhan yang jelas.
Selain log, pantau jumlah event gagal, antrean yang terus bertambah, waktu pemrosesan, dan event yang terlalu lama belum selesai. Indikator tersebut dapat membantu mendeteksi masalah sebelum banyak event tertunda.
Contoh Alur Retry Webhook
Berikut gambaran alur penerimaan webhook yang dilengkapi penyimpanan dan pemrosesan terpisah.
- Layanan WhatsApp API mengirimkan event ke endpoint webhook.
- Endpoint memvalidasi permintaan dan menyimpan event secara persisten.
- Jika penyimpanan berhasil, endpoint mengirimkan respons sukses.
- Worker mengambil event dari antrean.
- Worker memeriksa apakah event sudah pernah diproses.
- Jika belum, worker menjalankan proses bisnis dan mencatat hasilnya.
- Jika proses gagal, sistem menjalankan retry internal sesuai aturan.
- Jika percobaan terus gagal, event disimpan untuk pemeriksaan dan pemrosesan ulang.
Jika endpoint tidak merespons, pengirim mungkin mengirim ulang event sesuai kebijakan retry yang berlaku. Oleh sebab itu, pemeriksaan duplikasi tetap diperlukan meskipun aplikasi sudah menggunakan antrean.
Cara Menguji Retry Webhook
Sebelum digunakan pada sistem produksi, lakukan pengujian untuk memastikan event tetap tercatat saat terjadi gangguan.
Uji server tidak merespons
Hentikan layanan penerima atau buat endpoint tidak dapat dijangkau pada lingkungan pengujian. Amati apakah pengirim mencoba ulang dan bagaimana perilakunya setelah endpoint kembali aktif.
Hasil pengujian harus dibandingkan dengan kebijakan retry yang didokumentasikan oleh penyedia webhook.
Uji respons yang terlambat
Buat endpoint pengujian yang merespons lebih lambat dari biasanya. Periksa apakah terjadi timeout, pengiriman ulang, atau event duplikat.
Uji event yang sama dikirim dua kali
Kirim payload pengujian yang sama lebih dari sekali. Pastikan sistem tidak menggandakan pembaruan data atau tindakan bisnis yang seharusnya dilakukan satu kali.
Uji kegagalan worker
Buat proses worker gagal setelah event berhasil disimpan. Pastikan event tetap tersedia untuk dicoba kembali dan tidak dianggap selesai sebelum pemrosesan berhasil.
Uji pemulihan setelah server aktif kembali
Pulihkan server dan periksa apakah event yang tertunda diterima atau diproses sesuai kemampuan sistem. Pastikan juga ada cara untuk menemukan dan memproses ulang event yang gagal secara permanen.
Bagaimana Jika Webhook Tetap Tidak Diterima?
Jika event masih tidak masuk meskipun server sudah aktif, periksa beberapa kemungkinan berikut:
- URL webhook yang terdaftar tidak sesuai dengan endpoint aktif.
- Konfigurasi webhook belum tersimpan atau belum berlaku.
- Permintaan diblokir oleh firewall, proxy, atau aturan jaringan.
- Endpoint mengembalikan status HTTP yang tidak sesuai.
- Format body tidak dapat dibaca oleh aplikasi.
- Event tidak termasuk jenis notifikasi yang dikonfigurasi.
- Layanan pengirim tidak menyediakan retry otomatis untuk kondisi tersebut.
- Periode retry telah berakhir sehingga event perlu dipulihkan melalui mekanisme lain yang tersedia.
Untuk integrasi Whapi, gunakan dokumentasi integrasi webhook Whapi sebagai acuan konfigurasi. Periksa juga perilaku retry yang benar-benar didukung layanan sebelum menentukan jumlah percobaan atau jeda pengiriman.
Kesimpulan
Retry webhook membantu mengatasi kegagalan pengiriman ketika server tidak merespons, tetapi bukan satu-satunya solusi untuk menjaga data tetap aman.
Sistem yang andal perlu memastikan endpoint merespons dengan cepat setelah event tersimpan secara persisten, mencegah pemrosesan duplikat, menyediakan retry internal, dan mencatat event yang gagal. Dengan cara ini, gangguan sementara tidak langsung menyebabkan data hilang atau proses bisnis dijalankan berulang kali.
Hal terpenting adalah membedakan kegagalan pengiriman webhook dari kegagalan pemrosesan internal. Keduanya membutuhkan penanganan berbeda agar event WhatsApp dapat diproses secara konsisten.


