Integrasi Notifikasi Webhook

Webhook adalah mekanisme di mana Whapi secara otomatis mengirim data ke server penerima setiap kali ada aktivitas di nomor WhatsApp yang terhubung, seperti pesan masuk, perubahan status pesan, atau perubahan koneksi perangkat.

Tanpa webhook, satu-satunya cara mengetahui ada pesan masuk adalah dengan terus-menerus memanggil API secara berkala (polling), yang tidak efisien. Dengan webhook, data dikirim langsung ke server begitu event terjadi.

Prasyarat

• Aplikasi Whapi sudah terinstal dan nomor WhatsApp sudah terhubung
• Server atau endpoint publik yang bisa menerima HTTP POST request
• Untuk pengujian lokal Anda bisa menggunakan ngrok.

Cara Mengaktifkan Webhook

Langkah 1: Buka Pengaturan Perangkat

Masuk ke dashboard Whapi, pilih Perangkat, lalu klik Kelola Perangkat dan buka Kelola.

Langkah 2: Aktifkan Webhook

Di tab Fitur, aktifkan salah satu atau semua opsi webhook berikut sesuai kebutuhan:

Opsi Webhook	Fungsi
Webhook	Mengirim semua event utama: pesan masuk, status pesan, koneksi perangkat, aktivitas grup
Webhook Media	Mengirim data file yang diterima: gambar, video, dokumen. Bisa dalam format base64 atau Media Key
Webhook Story	Mengirim aktivitas story dari kontak yang terhubung

Langkah 3: Masukkan URL Endpoint

Di tab Webhook, Isi kolom URL dengan alamat endpoint server yang akan menerima data webhook. Contoh:

https://namaserver.com/webhook/whapi

Untuk pengujian tanpa server publik, gunakan URL sementara dari webhook.site atau play.svix.com, atau jalankan tunnel lokal dengan Ngrok.

Langkah 4: Pilih Format Media (Opsional)

Jika Webhook Media diaktifkan, pilih format pengiriman file:

• base64: File dikonversi ke string base64. Jika ingin mengembalikan ke file asli, silakan decode base64. (Ukuran payload akan sesuai dengan file yang dikirim)
• Media Key: Hanya dikirim kunci referensi. File diambil terpisah via endpoint GET /media/{media_key}. Cocok untuk menghemat ukuran payload.

Mendapatkan file dari webhook Mendapatkan file dari Media Key

Langkah 5: Pilih Tipe Notifikasi

Klik Kustomisasi Webhook untuk memilih tipe event yang akan dikirim. Daftar tipe event yang tersedia:

Tipe Event	Keterangan
ready	Perangkat sudah siap untuk mengirim pesan API
disconnected	Perangkat terputus dari layanan
message	Pesan teks atau media masuk
message_ack	Perubahan status pesan: sent, delivered, read, failed
change_state	Perubahan status koneksi perangkat
group_join	Anggota baru bergabung ke grup
group_leave	Anggota keluar dari grup
group_update	Perubahan informasi grup (nama, deskripsi, dll)
schedule	Notifikasi pesan terjadwal terkirim
poll_update	Notifikasi hasil voting whatsapp
fromMe	Notifikasi pesan yang dikirim ke nomor sendiri

Membuat Webhook Receiver di Server

PHP

// Mengambil body request mentah
$payload = file_get_contents('php://input');

// Mengonversi JSON menjadi array (jika payload dalam format JSON)
$data = json_decode($payload, true);

// Mencatat log ke file 'webhook.log'
if ($data) {
    file_put_contents('webhook.log', "[" . date('Y-m-d H:i:s') . "] Payload: " . $payload . PHP_EOL, FILE_APPEND);
    // Memberikan respon 200 OK ke pengirim
    http_response_code(200);
    echo "Webhook received successfully";
} else {
    http_response_code(400);
    echo "Invalid payload";
}

Python

 from flask import Flask, request, jsonify
 import logging

 app = Flask(__name__)

 # Konfigurasi logging dasar
 logging.basicConfig(level=logging.INFO)

 @app.route('/webhook', methods=['POST'])
 def webhook_receiver():
     # Mengambil data JSON dari request
     data = request.json
     
     if data:
         # Menampilkan log di konsol / terminal
         app.logger.info(f"Payload diterima: {data}")
         
         # Respon sukses
         return jsonify({"status": "success", "message": "Received"}), 200
     else:
         return jsonify({"status": "error", "message": "No data"}), 400

 if __name__ == '__main__':
     app.run(port=5000)

NodeJS ( Express )

const express = require('express');
const app = express();
const PORT = 3000;

// Middleware untuk membaca JSON body
app.use(express.json());

app.post('/webhook', (req, res) => {
    const payload = req.body;

    // Menampilkan log di konsol / terminal
    console.log('--- Webhook Received ---');
    console.log(JSON.stringify(payload, null, 2));
    console.log('------------------------');

    // Kirim respon balik dengan status 200
    res.status(200).send('Webhook processed');
});

app.listen(PORT, () => {
    console.log(`Server berjalan di http://localhost:${PORT}`);
});

info

Penting: Server webhook harus selalu mengembalikan HTTP 200 setelah menerima data. Jika Whapi tidak menerima respons 200, pengiriman webhook dianggap gagal dan akan dicatat di log error.

Menguji Webhook

Opsi 1: Menggunakan webhook.site

1. Buka webhook.site
2. Salin URL unik yang diberikan
3. Tempel URL tersebut ke kolom webhook di dashboard Whapi
4. Kirim pesan ke nomor yang terhubung
5. Lihat data JSON yang masuk di webhook.site secara real-time

Opsi 2: Menggunakan Ngrok untuk Server Lokal

Jika server receiver berjalan di komputer lokal, gunakan Ngrok untuk membuat URL publik sementara:

ngrok http 3001

Salin URL HTTPS yang diberikan Ngrok (contoh: https://abc123.ngrok.io) dan gunakan sebagai URL webhook di dashboard Whapi.

Panduan lengkap penggunaan Ngrok tersedia di halaman

Menjalankan WHAPI Lokal dengan Ngrok

Error Umum dan Solusinya

Kondisi	Penyebab	Solusi
Webhook tidak menerima data sama sekali	URL endpoint salah atau tidak bisa diakses publik	Periksa URL, pastikan server berjalan dan bisa diakses dari internet
Data diterima tapi tidak lengkap	Tipe event tidak dicentang di kustomisasi webhook	Buka kustomisasi webhook dan aktifkan tipe event yang dibutuhkan
Server menerima data tapi webhook dicatat error	Server tidak mengembalikan HTTP 200	Pastikan endpoint selalu return status 200 setelah memproses data
File media tidak ada dalam payload	Webhook Media belum diaktifkan	Aktifkan opsi Webhook Media di pengaturan perangkat
Payload terlalu besar untuk diproses	File media dikirim dalam format base64	Ganti ke format Media Key dan ambil file secara terpisah