Webhook
Terima pesan masuk, status pesan keluar, dan status perangkat secara seketika di server Anda.
Webhook mengirim kabar ke URL Anda setiap kali ada pesan masuk, status pesan keluar berubah, atau perangkat tersambung/terputus. URL webhook diatur per perangkat.
Hanya butuh status pesan yang Anda kirim? Webhook tidak wajib. Status bisa dicek kapan saja lewat Cek Status Pesan.
Pasang URL webhook
Buka Perangkat, klik titik tiga ( ⁝ ) pada perangkat, lalu pilih Webhook.

Isi Webhook URL dengan alamat endpoint Anda (HTTPS), atur opsi lain bila perlu, lalu klik Simpan. URL baru langsung diuji: bila uji kirim gagal, URL tetap tersimpan dan penyebabnya ditampilkan.

Klik ikon Test Webhook di kartu perangkat untuk memastikan URL menerima kiriman.
| Pengaturan | Fungsi |
|---|---|
| Webhook URL | Alamat yang menerima kiriman |
| Secret tanda tangan | Bila diisi, setiap kiriman ditandatangani. Lihat verifikasi tanda tangan |
| Format gambar & audio masuk | URL file (disarankan, berlaku 3 hari) atau Base64 di dalam payload. Maks. 16 MB |
| Kirim semua event | Matikan untuk memilih event tertentu saja, lihat memilih event |
Memakai n8n? Tambahkan node Webhook dengan method POST, lalu salin Production URL (…/webhook/…) ke NgirimWA dan aktifkan workflow. Test URL (…/webhook-test/…) hanya berfungsi saat Anda menekan Execute workflow.
Daftar event
| Event | Kapan dikirim |
|---|---|
message.received | Ada pesan masuk |
message.sent | Pesan keluar diterima server WhatsApp (centang 1) |
message.delivered | Pesan keluar sampai di HP penerima (centang 2) |
message.read | Pesan keluar dibaca (centang biru), bila penerima mengizinkan |
message.failed | Pesan keluar gagal, sebelum sampai ke WhatsApp atau ditolak WhatsApp |
device.connected | Perangkat tersambung |
device.disconnected | Perangkat terputus |
Memilih event
Semua event dikirim secara default. Di pengaturan webhook, matikan Kirim semua event lalu centang yang Anda perlukan, misalnya hanya message.failed dan device.disconnected. Event yang tidak dipilih tidak dikirim. Chatbot tetap berjalan, dan kiriman Test Webhook selalu terkirim.
Cara pengiriman
Setiap event dikirim sebagai POST JSON dengan header:
| Header | Isi |
|---|---|
X-NgirimWA-Event | Nama event, sama dengan event di body |
X-NgirimWA-Delivery | ID unik per event, sama di setiap percobaan ulang. Pakai untuk membuang duplikat |
X-NgirimWA-Attempt | Percobaan ke-berapa (1–6) |
X-NgirimWA-Signature | t=<unix>,v1=<hex>, hanya bila secret diisi |
- Balas dengan HTTP
2xxdalam 10 detik. Proses yang lama jalankan setelah membalas. - Bila server Anda tidak merespons atau membalas selain
2xx, kiriman diulang setelah 10 detik, 1, 5, 10, lalu 15 menit (6 percobaan, ±31 menit). HeaderRetry-Afterdihormati sampai 15 menit. - Balasan 410 berarti endpoint sudah tidak ada, sehingga kiriman tidak diulang.
- Redirect
301,302, dan303dihitung gagal, jadi isi URL tujuan akhirnya (misalnya langsunghttps://). Redirect307dan308diikuti. Pengecualian: Google Apps Script (script.google.com) memang membalas302setelah skrip berjalan, dan itu dihitung berhasil. Pastikan akses web app diatur ke Anyone. - Percobaan ulang memakai URL dan secret terbaru dari pengaturan perangkat.
- Pesan masuk berisi file di atas 1 MB dalam mode Base64 hanya dikirim sekali, tanpa percobaan ulang.
- Karena ada percobaan ulang, urutan event tidak dijamin. Simpan status yang tidak pernah mundur:
sent<delivered<read;failedhanya menimpa status sebelumdelivered.
Semua kiriman dan percobaannya tercatat di Perangkat → Riwayat Webhook, lengkap dengan kode respons, waktu respons, dan filter per event.

Jeda dan penonaktifan otomatis
Endpoint yang terus gagal tidak dikirimi tanpa henti:
| Kondisi | Yang terjadi |
|---|---|
| 10 kiriman gagal beruntun | Kiriman dijeda 5 menit, dan kartu perangkat menampilkan Webhook Bermasalah beserta penyebab terakhir. Setelah jeda, satu kiriman dicoba. Bila masih gagal, jeda naik menjadi 15 lalu 60 menit |
| 24 jam gagal terus | Email peringatan dikirim ke alamat akun Anda |
| 3 hari gagal terus | Webhook dinonaktifkan, kartu perangkat menampilkan Webhook Nonaktif, dan email pemberitahuan dikirim |
- Event yang terjadi selama jeda atau saat nonaktif tidak dikirim ulang. Status pesan keluar tetap bisa diambil lewat Cek Status Pesan.
- Satu kiriman berhasil mengembalikan webhook ke kondisi normal. Perangkat yang sedang sepi (tidak ada kiriman baru) tidak dinonaktifkan.
- Untuk mengaktifkan lagi webhook yang nonaktif: perbaiki endpoint Anda, buka pengaturan webhook perangkat, lalu klik Aktifkan Lagi. Mengganti Webhook URL juga mengaktifkannya kembali.
- Pesan WhatsApp, chatbot, dan fitur lain tidak terpengaruh oleh kondisi webhook.
Pesan masuk
{
"event": "message.received",
"timestamp": "2026-10-09T10:00:00.000Z",
"device": { "id": "uuid-perangkat", "name": "Toko Saya", "phone": "628111111111" },
"message": {
"id": "3EB0ABC123",
"from": "628222222222",
"sender_name": "Budi",
"type": "text",
"content": "Halo, saya mau tanya",
"info": {},
"timestamp": 1760004000,
"media_type": null,
"media": null,
"raw": {}
},
"metadata": { "is_group": false, "group_id": null, "is_lid_only": false }
}message.type | Isi |
|---|---|
text | Pesan teks |
image, audio | Gambar atau suara tanpa teks. File ada di message.media |
video, document, sticker | Media lain |
interactive_reply, button_reply, template_button_reply | Penerima menekan tombol: info.button_id, info.button_text |
list_reply, interactive_list_reply | Penerima memilih baris list: info.row_id, info.row_title, info.row_description |
location, contact, poll | Pesan khusus |
-
contentberisi teks yang dilihat penerima (label tombol atau judul baris). Untuk logika integrasi pakaiinfo.button_id/info.row_id, karena ID tidak berubah saat teks tampilan diganti. -
Pesan grup hanya dikirim dari grup yang diaktifkan di Balas di Grup (balasan AI tidak Mati, atau dipilih oleh trigger Chatbot Klasik). Isinya:
metadata.is_groupbernilaitrue,metadata.group_idberisi ID grup,message.fromberisi nomor pengirim, danmetadataditambah field berikut:Field Isi participantNomor pengirim di grup. Bila WhatsApp menyembunyikan nomornya, is_lid_onlybernilaitruedan field ini berisi ID pengirimmentioned_bottruebila pesan menyebut (@) nomor perangkatreply_to_bottruebila pesan membalas pesan dari nomor perangkat -
rawberisi objek pesan WhatsApp asli, untuk kebutuhan lanjutan.
Gambar & audio. Bila media_type berisi image atau audio, message.media berisi:
| Field | Isi |
|---|---|
url | Tautan unduh (mode URL), berlaku sampai url_expires_at |
base64 | Isi file (mode Base64) |
mimetype, size | Jenis dan ukuran file (byte) |
width, height | Ukuran gambar |
seconds, is_voice_note | Durasi audio; true bila voice note |
error | Bila file tidak bisa disediakan: too_large, download_failed, storage_failed |
Gambar atau audio yang punya teks/caption tetap bertipe text, dan filenya tetap ada di message.media.
Status pesan keluar
message.sent, message.delivered, message.read, dan message.failed membawa:
| Field | Isi |
|---|---|
id | ID pesan WhatsApp. null bila pesan gagal sebelum sampai ke WhatsApp |
to | Nomor tujuan |
status | sent, delivered, read, atau failed |
ack | 2 sent, 3 delivered, 4 read (tidak ada pada failed) |
tracking_id, ref_id | Dari respons kirim API. null untuk pesan dari kampanye, chatbot, atau dashboard |
error | Khusus failed: { code, message, wa_code }, lihat kode gagal kirim |
{
"event": "message.delivered",
"timestamp": "2026-10-09T10:00:03.540Z",
"device": { "id": "uuid-perangkat", "name": "Toko Saya", "phone": "628111111111" },
"message": {
"id": "3EB0XYZ789",
"to": "628222222222",
"ack": 3,
"status": "delivered",
"tracking_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx1",
"ref_id": "INV-2026-0042"
}
}Gagal sebelum sampai ke WhatsApp, misalnya perangkat terputus sampai melewati expires_in:
{
"event": "message.failed",
"message": {
"id": null,
"to": "628222222222",
"status": "failed",
"tracking_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx1",
"ref_id": "INV-2026-0042",
"error": { "code": "expired", "message": "Not sent before expires_at (device was offline or the queue was busy)", "wa_code": null }
}
}Ditolak WhatsApp: error berisi mis. { "code": "recipient_restricted", "wa_code": "463", ... } dan id terisi.
Field error_code dan error_message di dalam message sudah usang dan dihapus setelah 31 Januari 2027. Pakai message.error.code.
Perangkat
{
"event": "device.disconnected",
"timestamp": "2026-10-09T10:00:00.000Z",
"device": { "id": "uuid-perangkat", "name": "Toko Saya", "phone": "628111111111" },
"reason": "loggedOut",
"code": 401
}device.connected berbentuk sama tanpa reason dan code.
reason | Arti |
|---|---|
loggedOut | Perangkat dikeluarkan dari HP. Perlu scan QR ulang |
connectionReplaced | Akun dibuka di sambungan lain |
banned | Nomor diblokir WhatsApp |
restartRequired | Sambungan dimulai ulang, tersambung kembali otomatis |
code_<angka> | Alasan lain dari WhatsApp |
Verifikasi tanda tangan
Tanpa tanda tangan, siapa pun yang tahu URL Anda bisa mengirim kiriman palsu. Buat secret di pengaturan webhook, simpan di server Anda, lalu periksa setiap kiriman:
Ambil t dan v1 dari header X-NgirimWA-Signature.
Hitung HMAC-SHA256(secret, t + "." + rawBody). rawBody adalah body persis seperti diterima, bukan hasil parse ulang.
Bandingkan dengan v1 secara timing-safe, dan tolak bila t berselisih lebih dari 300 detik dari sekarang.
Node.js (Express)
import crypto from 'node:crypto';
import express from 'express';
const app = express();
const SECRET = process.env.NGIRIMWA_WEBHOOK_SECRET;
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
const parts = Object.fromEntries((req.get('X-NgirimWA-Signature') || '').split(',').map((kv) => kv.split('=')));
const t = Number(parts.t);
if (!t || Math.abs(Date.now() / 1000 - t) > 300) return res.status(401).end();
const expected = crypto.createHmac('sha256', SECRET).update(`${t}.${req.body}`).digest('hex');
const given = Buffer.from(parts.v1 || '', 'hex');
if (given.length !== 32 || !crypto.timingSafeEqual(given, Buffer.from(expected, 'hex'))) {
return res.status(401).end();
}
res.sendStatus(200);
const payload = JSON.parse(req.body);
// buang duplikat dengan req.get('X-NgirimWA-Delivery'), lalu proses payload
});PHP
<?php
$secret = getenv('NGIRIMWA_WEBHOOK_SECRET');
$raw = file_get_contents('php://input');
parse_str(str_replace(',', '&', $_SERVER['HTTP_X_NGIRIMWA_SIGNATURE'] ?? ''), $parts);
$t = (int) ($parts['t'] ?? 0);
if ($t === 0 || abs(time() - $t) > 300) { http_response_code(401); exit; }
if (!hash_equals(hash_hmac('sha256', $t . '.' . $raw, $secret), $parts['v1'] ?? '')) { http_response_code(401); exit; }
http_response_code(200);
$payload = json_decode($raw, true);
// buang duplikat dengan $_SERVER['HTTP_X_NGIRIMWA_DELIVERY'], lalu proses $payloadSetelah Putar ulang secret, secret lama langsung tidak berlaku. Perbarui di server Anda lebih dulu.