Webhook WhatsApp yang Andal: Idempotensi dan Retry

Webhook WhatsApp yang Andal: Idempotensi dan Retry

Webhook adalah pintu masuk event dari WhatsApp API ke sistem bisnis. Desain webhook yang andal harus memproses event cepat, mencegah pesan ganda, dan menyimpan jalur pemulihan saat layanan internal gagal. Ini penting untuk AI WhatsApp message gateway yang menangani notifikasi pesanan, percakapan pelanggan, dan handoff ke staf.

Jawaban singkat

Gunakan webhook tipis: validasi request, simpan event dengan ID unik, kirim respons sukses secepat mungkin, lalu proses pekerjaan di antrean. Terapkan idempotensi agar event yang sama tidak membuat dua pesan atau dua perubahan status. Retry hanya untuk kegagalan sementara, dengan batas percobaan dan backoff.

WhatsApp API bekerja sebagai sumber event, bukan satu-satunya sumber kebenaran bisnis. Status pesanan tetap harus dibaca dari sistem order. Gateway WhatsApp meneruskan event ke workflow yang sesuai, sedangkan AI conversation flow menyusun jawaban dari data yang sudah divalidasi.

Empat lapisan webhook

Lapisan pertama adalah verifikasi. Periksa token verifikasi saat endpoint didaftarkan, lalu validasi signature atau kredensial sesuai dokumentasi provider. Jangan menaruh secret di URL, log, atau kode frontend. Batasi endpoint hanya menerima metode dan content type yang dibutuhkan.

Lapisan kedua adalah penerimaan. Simpan payload mentah seperlunya bersama event ID, waktu diterima, nomor pengirim yang sudah diminimalkan, dan status pemrosesan. Hindari menyimpan seluruh data pribadi bila alur tidak memerlukannya.

Lapisan ketiga adalah deduplikasi. Buat kunci unik dari ID event provider. Bila provider atau gateway mengirim event yang sama dua kali, database harus menolak duplikat atau worker harus mengenalinya sebagai event yang sudah selesai. Kunci ini berbeda dari ID pesanan. Satu pesanan dapat menghasilkan beberapa event, seperti pembayaran diterima, paket diserahkan ke kurir, dan paket tiba.

Lapisan keempat adalah worker. Worker mengambil event dari antrean, memperbarui status internal, lalu menjalankan tindakan seperti mengirim delivery notification atau membuat tugas untuk staf. Pisahkan penerimaan webhook dari pengiriman pesan agar lonjakan event tidak membuat endpoint timeout.

Retry bukan izin mengirim ulang tanpa batas

Retry cocok untuk timeout, error jaringan, atau respons server sementara. Retry tidak cocok untuk request yang ditolak karena autentikasi, payload invalid, atau nomor tujuan tidak valid. Klasifikasikan error sebelum menentukan tindakan.

Gunakan exponential backoff dengan batas maksimum. Contoh sederhana: percobaan kedua menunggu 2 detik, berikutnya 4 detik, lalu 8 detik, dengan jitter acak. Simpan jumlah percobaan dan alasan kegagalan. Setelah batas tercapai, pindahkan event ke dead-letter queue untuk pemeriksaan manusia atau proses ulang terkontrol.

Idempotensi harus berlaku di dua tempat. Worker harus idempoten ketika memperbarui order, dan pengirim pesan harus punya idempotency key atau catatan pengiriman sendiri. Tanpa lapisan kedua, retry worker dapat menghasilkan dua pesan WhatsApp meski status order hanya berubah sekali.

Menghubungkan status order ke pesan

Mulai dari state machine kecil. Misalnya, status paid memicu pesan konfirmasi, status packed memicu pesan persiapan, dan status shipped memicu nomor pelacakan. Setiap transisi perlu menyimpan versi status atau timestamp. Worker tidak boleh mengirim status shipped jika event yang baru diproses ternyata lebih lama daripada status delivered.

Pisahkan pesan transaksional dari promosi. Pelanggan harus bisa menemukan update pesanan tanpa membaca penawaran lain. Template harus menjelaskan status, waktu pembaruan bila tersedia, dan langkah berikutnya. Jangan kirim alamat lengkap, token, atau data internal ke percakapan pelanggan.

Untuk notifikasi pengiriman, siapkan fallback bila kurir belum memberi nomor resi. Jawaban yang jujur seperti “pesanan sudah diserahkan, nomor pelacakan belum tersedia” lebih aman daripada mengarang estimasi. Pola ini melengkapi WhatsApp API untuk notifikasi pesanan.

AI dan human handoff

AI cocok untuk mengklasifikasikan pertanyaan, mengambil status dari tool yang diizinkan, dan menyusun jawaban singkat. AI tidak boleh mengubah status order tanpa izin workflow atau menebak data yang kosong.

Alihkan percakapan ke manusia ketika pelanggan meminta staf, mengajukan refund, menyampaikan keluhan serius, atau sistem menemukan data yang tidak cocok. Handoff harus membawa ringkasan percakapan, ID order, status terakhir, event yang gagal, dan alasan eskalasi. Tanpa konteks ini, automation hanya memindahkan beban ke staf dan pelanggan.

Tim juga perlu melihat metrik: waktu respons webhook, umur antrean, rasio retry, duplicate event, pesan gagal, dan waktu dari handoff ke balasan staf. Alert pada antrean yang menumpuk lebih berguna daripada hanya memantau uptime endpoint.

Managed atau open-source gateway?

Managed WhatsApp gateway mengurangi beban merawat koneksi, monitoring, dan operasi pesan. Open-source WhatsApp gateway memberi kontrol lebih atas deployment dan kode, tetapi tim harus menanggung patch keamanan, backup, observability, dan pemulihan saat koneksi atau provider berubah.

Pilih berdasarkan kemampuan operasional, kebutuhan kontrol data, integrasi, dan target pemulihan. Uji webhook duplikat, worker mati, database lambat, provider timeout, dan handoff bersamaan sebelum membuka alur untuk pelanggan. Untuk tim yang ingin memetakan kebutuhan nomor, workflow, dan integrasi, lihat platform komunikasi bisnis MauKirim.

Bacaan terkait

• Notifikasi Pengiriman Lewat WhatsApp
• Integrasi WhatsApp dengan Workflow Tim
• AI WhatsApp untuk Status Pesanan dan Handoff

Mulai dengan satu event dan satu tindakan. Simpan event ID, ukur retry, lalu tambahkan AI dan handoff setelah jalur dasar stabil. Dokumentasi resmi WhatsApp Cloud API dan panduan API provider tetap menjadi rujukan untuk detail autentikasi, webhook, dan batas platform.