Jenis Event Webhook

NgirimWA mengirim payload JSON ke webhook_url device Anda saat event-event berikut terjadi. Konfigurasi webhook URL ada di Dashboard → Perangkat → Edit.

Semua event memakai HTTP POST dengan header:

Content-Type: application/json
User-Agent: NgirimWA-Webhook/1.0

Daftar Event

Event	Trigger
`message.received`	Pesan masuk dari kontak lain
`message.sent`	Pesan keluar berhasil terkirim ke server WhatsApp (centang 1)
`message.delivered`	Pesan keluar diterima device penerima (centang 2)
`message.read`	Pesan keluar dibaca penerima (centang 2 biru)
`message.failed`	Pesan keluar gagal dikirim
`device.connected`	Device WhatsApp Anda baru saja online
`device.disconnected`	Device WhatsApp Anda baru saja offline

Read receipt hanya muncul bila penerima mengaktifkan "Read Receipts" di pengaturan privasi WhatsApp mereka.

`message.received`

Pesan masuk — text, media, button reply, list reply, dll.

{
  "event": "message.received",
  "timestamp": "2026-05-15T10:00:00.000Z",
  "device": {
    "id": "uuid-device",
    "name": "Toko Saya",
    "phone": "628111111111"
  },
  "message": {
    "id": "3EB0ABC123",
    "from": "628222222222",
    "sender_name": "Budi",
    "type": "text",
    "content": "Halo, saya mau tanya",
    "info": {},
    "timestamp": 1747300800,
    "raw": { /* objek message Baileys mentah */ }
  },
  "metadata": {
    "is_group": false,
    "group_id": null,
    "is_lid_only": false
  }
}

Tipe `message.type`

Tipe	Keterangan
`text`	Pesan teks biasa
`image` / `video` / `audio` / `document` / `sticker`	Pesan media
`buttons_response`	User menekan tombol — lihat `info.selected_id`
`list_response`	User memilih item list — lihat `info.selected_row_id`
`location` / `contact` / `poll`	Pesan khusus

`message.sent`

Pesan keluar diterima server WhatsApp.

{
  "event": "message.sent",
  "timestamp": "2026-05-15T10:00:01.123Z",
  "device": { "id": "...", "name": "...", "phone": "628111111111" },
  "message": {
    "id":   "3EB0XYZ789",
    "to":   "628222222222",
    "ack":  2
  }
}

`message.delivered`

{
  "event": "message.delivered",
  "timestamp": "...",
  "device": { "id": "...", "name": "...", "phone": "..." },
  "message": { "id": "3EB0XYZ789", "to": "628222222222", "ack": 3 }
}

`message.read`

{
  "event": "message.read",
  "timestamp": "...",
  "device": { "id": "...", "name": "...", "phone": "..." },
  "message": { "id": "3EB0XYZ789", "to": "628222222222", "ack": 4 }
}

`message.failed`

Pesan gagal terkirim. Field error.code mengikuti kode error Baileys/WhatsApp.

{
  "event": "message.failed",
  "timestamp": "...",
  "device": { "id": "...", "name": "...", "phone": "..." },
  "message": {
    "id":  "3EB0XYZ789",
    "to":  "628222222222",
    "ack": "failed",
    "error": {
      "code": 408,
      "message": "Recipient not reachable"
    }
  }
}

`device.connected`

Device baru saja terhubung ke WhatsApp.

{
  "event": "device.connected",
  "timestamp": "2026-05-15T10:00:00.000Z",
  "device": {
    "id":    "uuid-device",
    "name":  "Toko Saya",
    "phone": "628111111111"
  }
}

`device.disconnected`

Device terputus. reason mengikuti kode disconnect Baileys:

loggedOut — di-logout dari ponsel
connectionClosed — koneksi putus mendadak
restartRequired — perlu reconnect
timedOut — timeout
badSession — sesi rusak, perlu scan ulang

{
  "event": "device.disconnected",
  "timestamp": "...",
  "device": {
    "id":    "uuid-device",
    "name":  "Toko Saya",
    "phone": "628111111111"
  },
  "reason": "loggedOut",
  "code":   401
}

Praktik Terbaik Konsumsi Webhook

Balas dengan HTTP 2xx secepatnya — webhook timeout di NgirimWA adalah 5 detik. Bila proses panjang, antrian-kan dulu lalu return 200.

Idempoten berdasarkan message.id — event yang sama bisa terkirim ulang (network retry). Gunakan ID sebagai dedup key.

Filter berdasarkan event — handler Anda sebaiknya switch (payload.event) { ... } agar mudah dikembangkan saat event baru ditambahkan.

Pantau di Dashboard → Riwayat Webhook — lihat success rate dan response time per event. Failure rate tinggi biasanya berarti endpoint Anda timeout atau return 5xx.

Jenis Event Webhook

On this page