Tutorial Webhook WhatsApp Cloud API: Terima dan Kirim Pesan Otomatis

Webhook adalah jantung dari WhatsApp Cloud API. Tanpa webhook, kamu tidak bisa menerima notifikasi pesan masuk dari pelanggan. Tanpa webhook, sistem kamu tidak tahu kapan pesan terkirim, dibaca, atau gagal. Singkatnya, webhook adalah "telinga" yang mendengarkan semua event di WhatsApp Business API.

Artikel ini adalah tutorial teknis untuk developer yang ingin setup webhook WhatsApp Cloud API dari nol.

Apa Itu Webhook?

Webhook adalah mekanisme di mana satu aplikasi mengirim data secara real-time ke aplikasi lain ketika suatu event terjadi. Dalam konteks WhatsApp Cloud API, Meta mengirim HTTP POST request ke URL yang kamu tentukan setiap kali ada event — pesan masuk, status pesan berubah, atau error terjadi.

Berbeda dengan polling di mana kamu harus terus-menerus mengecek apakah ada pesan baru, webhook bersifat push-based. Meta yang "memberitahu" kamu, bukan kamu yang harus bertanya terus-menerus.

Prasyarat

Sebelum memulai, pastikan kamu sudah memiliki akun WhatsApp Cloud API yang aktif di Meta for Developers, server atau endpoint yang bisa diakses publik dengan HTTPS (bisa menggunakan VPS, Cloudflare Workers, Railway, Vercel, atau Ngrok untuk testing), dan kemampuan programming dasar terutama HTTP request handling.

Langkah 1: Siapkan Endpoint Webhook

Webhook endpoint harus memenuhi dua syarat: bisa diakses publik melalui internet dan menggunakan HTTPS. Untuk development dan testing, kamu bisa menggunakan Ngrok yang membuat tunnel dari localhost ke URL publik — gratis untuk testing. Cloudflare Workers juga bagus karena serverless dan gratis untuk volume rendah. Railway atau Render menyediakan hosting gratis dengan HTTPS otomatis.

Untuk production, gunakan VPS atau cloud server dengan domain dan SSL certificate sendiri. Endpoint harus mampu merespon dengan cepat — Meta mengharapkan response dalam beberapa detik.

Langkah 2: Implementasi Verification Endpoint

Meta memverifikasi webhook kamu dengan mengirim GET request yang berisi tiga parameter: hub.mode yang nilainya selalu "subscribe", hub.verify_token yaitu token yang kamu tentukan sendiri, dan hub.challenge yaitu string random yang harus kamu kembalikan.

Server kamu harus mengecek apakah hub.verify_token cocok dengan token yang kamu set. Jika cocok, kembalikan nilai hub.challenge dengan status 200. Jika tidak cocok, kembalikan status 403.

Logicnya sederhana: terima GET request, validasi token, kembalikan challenge. Ini adalah "handshake" antara Meta dan server kamu.

Langkah 3: Daftarkan Webhook di Meta

Buka Meta for Developers, navigasi ke aplikasi WhatsApp kamu, lalu ke Configuration dan Webhook. Masukkan Callback URL yaitu URL endpoint webhook kamu dan Verify Token yaitu token yang kamu tentukan di kode server.

Klik "Verify and Save." Meta akan mengirim GET request ke URL kamu. Jika verification berhasil, webhook tersimpan. Setelah itu, subscribe ke field "messages" untuk menerima notifikasi pesan masuk.

Langkah 4: Handle Pesan Masuk

Setelah webhook aktif, Meta akan mengirim POST request setiap kali ada event. Payload berisi informasi tentang event yang terjadi. Untuk pesan masuk dari pelanggan, payload berisi data pengirim, jenis pesan (teks, gambar, lokasi, dan lain-lain), konten pesan, serta timestamp.

Server kamu perlu memproses payload ini, mengekstrak informasi yang diperlukan, dan melakukan aksi yang sesuai — misalnya menyimpan ke database, meneruskan ke agen CS, atau memicu chatbot.

Tipe pesan yang bisa kamu terima meliputi text berupa pesan teks biasa, image berupa gambar dengan media ID, document berupa file dokumen, location berupa koordinat lokasi, contacts berupa kartu kontak, interactive berupa respon dari pesan interaktif seperti button reply atau list reply, serta reaction berupa emoji reaction pada pesan.

Langkah 5: Kirim Pesan Otomatis

Setelah bisa menerima pesan, langkah selanjutnya adalah membalas secara otomatis. Untuk mengirim pesan, kamu membuat POST request ke endpoint Messages API Meta dengan body yang berisi messaging_product bernilai "whatsapp", nomor tujuan, tipe pesan, dan konten pesan.

Kamu bisa mengirim berbagai jenis pesan: text untuk pesan teks biasa yang bisa dikirim dalam customer window 24 jam, template untuk pesan menggunakan template yang sudah disetujui dan wajib digunakan di luar customer window, image atau video atau document untuk pesan media, serta interactive untuk pesan dengan tombol atau daftar.

Langkah 6: Handle Status Updates

Selain pesan masuk, webhook juga menerima notifikasi status pesan yang kamu kirim. Status yang mungkin diterima: sent berarti pesan sudah terkirim ke server WhatsApp, delivered berarti pesan sudah sampai di device penerima, read berarti pesan sudah dibaca penerima, dan failed berarti pengiriman gagal beserta error code-nya.

Tracking status ini penting untuk analytics dan untuk mendeteksi masalah pengiriman.

Tips Pengembangan

Pertama, selalu respond webhook dengan status 200 secepat mungkin. Proses data secara asynchronous di background. Jika kamu memproses terlalu lama, Meta akan menganggap webhook gagal dan retry.

Kedua, implementasikan idempotency. Meta bisa mengirim webhook yang sama lebih dari sekali. Pastikan sistem kamu bisa handle duplikat tanpa efek samping.

Ketiga, log semua payload webhook untuk debugging. Saat ada masalah, log ini akan sangat membantu.

Keempat, gunakan message queue untuk volume tinggi. Untuk bisnis yang menerima ribuan pesan per menit, proses webhook langsung bisa overwhelming. Gunakan queue seperti Redis atau RabbitMQ untuk buffering.

Kelima, setup monitoring dan alerting. Webhook yang down berarti kamu tidak menerima pesan dari pelanggan. Setup monitoring untuk mendeteksi downtime secepat mungkin.

Keamanan Webhook

Beberapa best practice keamanan: validasi signature dari Meta di setiap request untuk memastikan request benar-benar dari Meta bukan dari pihak ketiga, gunakan HTTPS dengan certificate yang valid, jangan expose token atau credential di URL, rate limit endpoint webhook untuk mencegah abuse, dan simpan App Secret dengan aman dan jangan hardcode di source code.

Kesimpulan

Webhook adalah komponen fundamental dari WhatsApp Cloud API yang memungkinkan komunikasi dua arah secara real-time. Meskipun setup awalnya membutuhkan kemampuan teknis, hasilnya sangat worth it — kamu mendapat kontrol penuh atas alur komunikasi WhatsApp bisnis.

Untuk developer yang baru mulai, gunakan Ngrok untuk testing lokal, implementasikan verification dan message handling dasar, lalu scale up secara bertahap.

Bukan developer tapi butuh auto-reply WhatsApp? Balaswa menyediakan semua ini tanpa perlu coding — setup dalam hitungan menit, bukan hari.