NgirimWA Docs

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.

Menu titik tiga pada kartu perangkat

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.

Jendela pengaturan webhook

Klik ikon Test Webhook di kartu perangkat untuk memastikan URL menerima kiriman.

PengaturanFungsi
Webhook URLAlamat yang menerima kiriman
Secret tanda tanganBila diisi, setiap kiriman ditandatangani. Lihat verifikasi tanda tangan
Format gambar & audio masukURL file (disarankan, berlaku 3 hari) atau Base64 di dalam payload. Maks. 16 MB
Kirim semua eventMatikan 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

EventKapan dikirim
message.receivedAda pesan masuk
message.sentPesan keluar diterima server WhatsApp (centang 1)
message.deliveredPesan keluar sampai di HP penerima (centang 2)
message.readPesan keluar dibaca (centang biru), bila penerima mengizinkan
message.failedPesan keluar gagal, sebelum sampai ke WhatsApp atau ditolak WhatsApp
device.connectedPerangkat tersambung
device.disconnectedPerangkat 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:

HeaderIsi
X-NgirimWA-EventNama event, sama dengan event di body
X-NgirimWA-DeliveryID unik per event, sama di setiap percobaan ulang. Pakai untuk membuang duplikat
X-NgirimWA-AttemptPercobaan ke-berapa (1–6)
X-NgirimWA-Signaturet=<unix>,v1=<hex>, hanya bila secret diisi
  • Balas dengan HTTP 2xx dalam 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). Header Retry-After dihormati sampai 15 menit.
  • Balasan 410 berarti endpoint sudah tidak ada, sehingga kiriman tidak diulang.
  • Redirect 301, 302, dan 303 dihitung gagal, jadi isi URL tujuan akhirnya (misalnya langsung https://). Redirect 307 dan 308 diikuti. Pengecualian: Google Apps Script (script.google.com) memang membalas 302 setelah 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; failed hanya menimpa status sebelum delivered.

Semua kiriman dan percobaannya tercatat di Perangkat → Riwayat Webhook, lengkap dengan kode respons, waktu respons, dan filter per event.

Riwayat Webhook

Jeda dan penonaktifan otomatis

Endpoint yang terus gagal tidak dikirimi tanpa henti:

KondisiYang terjadi
10 kiriman gagal beruntunKiriman 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 terusEmail peringatan dikirim ke alamat akun Anda
3 hari gagal terusWebhook 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.typeIsi
textPesan teks
image, audioGambar atau suara tanpa teks. File ada di message.media
video, document, stickerMedia lain
interactive_reply, button_reply, template_button_replyPenerima menekan tombol: info.button_id, info.button_text
list_reply, interactive_list_replyPenerima memilih baris list: info.row_id, info.row_title, info.row_description
location, contact, pollPesan khusus
  • content berisi teks yang dilihat penerima (label tombol atau judul baris). Untuk logika integrasi pakai info.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_group bernilai true, metadata.group_id berisi ID grup, message.from berisi nomor pengirim, dan metadata ditambah field berikut:

    FieldIsi
    participantNomor pengirim di grup. Bila WhatsApp menyembunyikan nomornya, is_lid_only bernilai true dan field ini berisi ID pengirim
    mentioned_bottrue bila pesan menyebut (@) nomor perangkat
    reply_to_bottrue bila pesan membalas pesan dari nomor perangkat
  • raw berisi objek pesan WhatsApp asli, untuk kebutuhan lanjutan.

Gambar & audio. Bila media_type berisi image atau audio, message.media berisi:

FieldIsi
urlTautan unduh (mode URL), berlaku sampai url_expires_at
base64Isi file (mode Base64)
mimetype, sizeJenis dan ukuran file (byte)
width, heightUkuran gambar
seconds, is_voice_noteDurasi audio; true bila voice note
errorBila 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:

FieldIsi
idID pesan WhatsApp. null bila pesan gagal sebelum sampai ke WhatsApp
toNomor tujuan
statussent, delivered, read, atau failed
ack2 sent, 3 delivered, 4 read (tidak ada pada failed)
tracking_id, ref_idDari respons kirim API. null untuk pesan dari kampanye, chatbot, atau dashboard
errorKhusus 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.

reasonArti
loggedOutPerangkat dikeluarkan dari HP. Perlu scan QR ulang
connectionReplacedAkun dibuka di sambungan lain
bannedNomor diblokir WhatsApp
restartRequiredSambungan 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 $payload

Setelah Putar ulang secret, secret lama langsung tidak berlaku. Perbarui di server Anda lebih dulu.

On this page