Panduan Webhook WhatsApp untuk Integrasi Custom: Terima Data Real-Time

Webhook adalah fondasi dari setiap integrasi WhatsApp yang serius. Tanpa webhook, sistem kamu buta — tidak tahu kapan pesan masuk, kapan pesan dibaca, atau kapan terjadi error. Dengan webhook, setiap event di WhatsApp langsung terpantau secara real-time.

Artikel ini adalah panduan teknis komprehensif tentang webhook WhatsApp Cloud API — dari konsep dasar hingga implementasi production-ready.

Konsep Webhook

Webhook berbeda dari API call biasa. Dalam API call tradisional, kamu yang meminta data dari server — ini disebut polling. Dalam webhook, server yang memberitahu kamu saat ada data baru — ini disebut push notification.

Untuk WhatsApp, Meta mengirim HTTP POST request ke URL endpoint yang kamu tentukan setiap kali terjadi event — pesan masuk, status pesan berubah, atau error. Endpoint kamu harus bisa menerima request ini, memproses datanya, dan merespon dengan cepat.

Setup Webhook

Langkah 1: Siapkan Endpoint

Endpoint webhook harus memenuhi syarat: accessible via internet, menggunakan HTTPS, dan mampu merespon dalam beberapa detik. Opsi hosting untuk development meliputi Ngrok untuk tunnel localhost, Cloudflare Workers yang serverless dan gratis untuk volume rendah, Railway atau Render yang gratis tier dengan HTTPS otomatis, dan Replit untuk prototyping cepat. Untuk production gunakan VPS dengan domain dan SSL sendiri, cloud functions di AWS Lambda atau Google Cloud Functions, atau dedicated server.

Langkah 2: Implementasi Verification

Meta memverifikasi webhook dengan mengirim GET request berisi tiga parameter: hub.mode dengan nilai "subscribe," hub.verify_token yaitu token yang kamu tentukan, dan hub.challenge berupa string yang harus dikembalikan.

Logicnya: cek apakah mode adalah "subscribe" dan verify_token cocok. Jika ya, kembalikan challenge dengan status 200. Jika tidak, kembalikan status 403.

Langkah 3: Registrasi di Meta

Di Meta Developer Console, navigasi ke app WhatsApp kamu kemudian Configuration kemudian Webhook. Masukkan Callback URL dan Verify Token. Klik Verify and Save. Subscribe ke field "messages."

Langkah 4: Handle Incoming Events

Setelah webhook aktif, Meta mengirim POST request untuk setiap event. Payload berisi informasi berbeda tergantung tipe event.

Tipe Event yang Diterima

Message Events

Dikirim saat pelanggan mengirim pesan. Data meliputi: pengirim berupa nomor telepon, timestamp, tipe pesan apakah text, image, document, location, contacts, interactive, atau button, dan konten pesan. Untuk media seperti gambar atau dokumen, payload berisi media ID yang perlu di-download terpisah melalui Media API.

Status Events

Dikirim saat status pesan yang kamu kirim berubah. Status meliputi: sent berarti pesan terkirim ke server WhatsApp, delivered berarti pesan sampai di device penerima, read berarti pesan dibaca, dan failed berarti gagal terkirim dengan error code.

Error Events

Dikirim saat terjadi error — misalnya nomor tidak valid, rate limit exceeded, atau template tidak ditemukan. Error code membantu diagnosa masalah.

Best Practice Production

Respond Cepat

Meta mengharapkan response 200 OK dalam beberapa detik. Jika endpoint terlalu lambat, Meta menganggap webhook gagal dan melakukan retry. Solusinya, terima request dan respond 200 segera, lalu proses data secara asynchronous di background menggunakan message queue.

Idempotency

Meta bisa mengirim webhook yang sama lebih dari sekali. Implementasikan idempotency — cek apakah event sudah pernah diproses sebelum memproses ulang. Gunakan message ID sebagai unique identifier.

Signature Validation

Validasi X-Hub-Signature header di setiap request untuk memastikan request benar-benar dari Meta. Ini mencegah spoofed requests dari pihak yang tidak berwenang.

Queue System

Untuk volume tinggi, jangan proses webhook secara synchronous. Gunakan message queue seperti Redis, RabbitMQ, atau Amazon SQS. Webhook handler hanya menerima data dan memasukkan ke queue. Worker terpisah yang memproses queue dan melakukan aksi seperti membalas pesan atau update database.

Monitoring

Setup monitoring untuk endpoint webhook. Alert jika webhook down, jika error rate meningkat, atau jika processing time melampaui threshold. Tools seperti Uptime Robot atau Grafana bisa membantu.

Logging

Log setiap webhook yang diterima — minimal timestamp, tipe event, dan status processing. Log ini sangat berharga untuk debugging saat terjadi masalah.

Kesimpulan

Webhook adalah pintu masuk data real-time dari WhatsApp ke sistem kamu. Setup yang benar dan robust menjadi fondasi untuk semua integrasi WhatsApp yang lebih kompleks — dari chatbot hingga CRM integration.

Investasikan waktu untuk implementasi yang proper sejak awal — idempotency, signature validation, dan queue system. Ini akan menghemat banyak sakit kepala di kemudian hari.

Bukan developer tapi butuh auto-reply WhatsApp? Balaswa menyediakan semua infrastruktur webhook tanpa perlu coding — tinggal setup dan jalan.