> ## Documentation Index
> Fetch the complete documentation index at: https://gowa-docs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook

> Terima event WhatsApp sebagai permintaan HTTP POST bertanda tangan: konfigurasi, jenis event, format payload, tanda tangan, dan percobaan ulang.

GOWA mengirim dokumen JSON melalui POST ke URL Anda untuk setiap event WhatsApp yang diterimanya: pesan, tanda terima, reaksi, pengeditan, penghapusan, indikator mengetik, perubahan grup, label, newsletter, dan panggilan.

Tidak ada endpoint pendaftaran webhook. Konfigurasikan webhook saat startup, atau per perangkat melalui `/devices/{device_id}/webhook`.

## Cara kerja pengiriman

```mermaid theme={null}
sequenceDiagram
    autonumber
    participant WA as WhatsApp
    participant G as GOWA
    participant R as Your receiver
    WA->>G: Event (whatsmeow)
    G->>G: Skip if chat/sender matches WHATSAPP_WEBHOOK_IGNORE_JIDS
    G->>G: Resolve targets (per-device webhook or global WHATSAPP_WEBHOOK)
    G->>G: Skip target if event not in its allowlist (WHATSAPP_WEBHOOK_EVENTS)
    loop Up to 5 attempts, 10 s timeout each
        G->>R: POST JSON {event, device_id, session_id, payload}<br/>X-Hub-Signature-256: sha256=HMAC(body, secret)
        R->>R: Verify HMAC over raw body
        alt 2xx
            R-->>G: 200 OK (delivered, stop)
        else non-2xx or network error
            R-->>G: Error
            G->>G: Wait 1 s, 2 s, 4 s, then 8 s before the next attempt
        end
    end
    Note over G: After the 5th failure the event is logged and dropped
```

Pengiriman ke setiap URL tujuan dilakukan secara independen, dengan secret dan percobaan ulang masing-masing.

## Konfigurasi

```bash theme={null}
# one or more URLs, comma-separated
WHATSAPP_WEBHOOK=https://example.com/wa-hook,https://backup.example.com/wa-hook
WHATSAPP_WEBHOOK_SECRET=replace-with-a-private-key # stable HMAC key
WHATSAPP_WEBHOOK_EVENTS=message,message.ack # optional allowlist; empty = all events
WHATSAPP_WEBHOOK_IGNORE_JIDS=@g.us          # optional; skip chats or senders
WHATSAPP_WEBHOOK_INSECURE_SKIP_VERIFY=false # verify HTTPS certificates
WHATSAPP_WEBHOOK_ALL_DEVICE_RECEIPTS=false  # optional linked-device receipts
```

Flag yang setara: `--webhook`, `--webhook-secret`, `--webhook-events`, `--webhook-ignore-jids`, `--webhook-insecure-skip-verify`, dan `--webhook-all-device-receipts`.

Tetapkan kunci penandatanganan privat secara eksplisit. Jika kunci tidak diatur atau menggunakan nilai lama yang dipublikasikan, yaitu `secret`, GOWA akan membuat kunci acak yang berubah setiap restart dan mencatat peringatan. Penerima memerlukan kunci bersama yang ditetapkan secara eksplisit agar dapat memverifikasi tanda tangan setelah restart. Sertifikat HTTPS diverifikasi secara default.

## Event

| Event | Dipicu saat |
| - | - |
| `message` | Pesan diterima (teks, media, kontak, lokasi, polling, dan sebagainya). `is_from_me` bernilai `true` untuk pesan yang dikirim oleh akun ini. |
| `message.reaction` | Seseorang memberikan reaksi pada pesan. |
| `message.revoked` | Pesan dihapus untuk semua orang. |
| `message.edited` | Pesan diedit. |
| `message.ack` | Tanda terima pengiriman atau pembacaan (`receipt_type`: `delivered`, `read`, ...). |
| `message.deleted` | Pesan dihapus hanya untuk Anda. |
| `chat_presence` | Kontak mulai atau berhenti mengetik atau merekam. |
| `presence` | Kontak yang dilanggan menjadi online atau offline. Memerlukan langganan presence dan klien berstatus tersedia. |
| `group.participants` | Anggota bergabung, keluar, dijadikan admin, atau diberhentikan sebagai admin (`type`: `join`, `leave`, `promote`, `demote`). |
| `group.info` | Nama grup berubah. Payload menyertakan `name` baru dan, jika diketahui, `name_set_by`. |
| `group.joined` | Akun Anda ditambahkan ke grup. |
| `label.edit` | Label WhatsApp Business dibuat atau diubah. |
| `label.association` | Label diterapkan pada atau dihapus dari chat. |
| `newsletter.joined` / `newsletter.left` | Anda mengikuti atau berhenti mengikuti kanal. |
| `newsletter.message` | Pembaruan langsung jumlah tayangan, penerusan, dan reaksi untuk postingan kanal yang dilanggan. |
| `newsletter.mute` | Pengaturan bisukan kanal berubah. |
| `call.offer` | Panggilan masuk. Jika `WHATSAPP_AUTO_REJECT_CALL=true`, panggilan ditolak secara otomatis. |
| `device.logged_out` | WhatsApp membuat perangkat logout, beserta kode alasannya. |
| `device.temporary_ban` | WhatsApp memblokir akun untuk sementara. |
| `device.reachout_timelock` | WhatsApp mengaktifkan atau mencabut pembatasan untuk memulai chat baru. |

Nama event dalam daftar yang diizinkan tidak membedakan huruf besar dan kecil.

## Payload

Setiap permintaan menggunakan struktur pembungkus yang sama:

```json theme={null}
{
  "event": "message",
  "device_id": "628123456789@s.whatsapp.net",
  "session_id": "sales",
  "payload": {
    "id": "3EB0C127D7BACC83D6A1",
    "chat_id": "628987654321@s.whatsapp.net",
    "from": "628987654321@s.whatsapp.net",
    "from_lid": "251556368777322@lid",
    "from_name": "John Doe",
    "sender_display_name": "John Doe",
    "timestamp": "2026-10-15T10:30:00Z",
    "is_from_me": false,
    "body": "Hello, how are you?"
  }
}
```

| Field | Deskripsi |
| - | - |
| `event` | Salah satu nama event di atas. |
| `device_id` | JID akun yang menerima event. Event perangkat tidak menyertakannya jika slot belum memiliki JID. |
| `session_id` | ID slot, misalnya ID dari `POST /devices`. Slot yang dibuat otomatis dapat menggunakan JID WhatsApp. Event perangkat selalu menyertakannya. Event lain mungkin tidak menyertakannya jika JID tidak dapat dipetakan ke slot. |
| `payload` | Data khusus event. Field umum: `id`, `chat_id`, `from`, `from_lid`, `from_name`, `sender_display_name`, `timestamp` (RFC 3339), `is_from_me`. |

Balasan menambahkan `replied_to_id` dan `quoted_body`. Tanda terima menggunakan `ids` (array) dan `receipt_type`. Event peserta grup menyertakan `chat_id`, `type`, dan `jids`. Perubahan nama grup menggunakan struktur `group.info` tersendiri.

`sender_display_name` hanya muncul jika `from` berupa string yang tidak kosong. Untuk pengirim lain, GOWA memprioritaskan nama kontak tersimpan, push name dari event langsung, push name tersimpan, nama bisnis, lalu bagian pengguna dari JID. Untuk akun aktif, GOWA memprioritaskan push name akun, lalu identitas JID-nya. Penentuan nama dilakukan sebisa mungkin berdasarkan data yang tersedia. Field lama `from_name` tetap berisi push name dari event pesan.

Pesan masuk dapat menyertakan `is_business: true`, `verified_name`, dan `verified_level` jika WhatsApp menyediakan sertifikat nama terverifikasi. Field ini tidak disertakan jika sertifikat tidak tersedia. Ketiadaannya tidak menentukan apakah pengirim merupakan bisnis, dan `verified_level` adalah nilai mentah dari upstream, bukan jaminan adanya lencana resmi.

### Media

Dengan `WHATSAPP_AUTO_DOWNLOAD_MEDIA=true` (default), media disimpan di `statics/media/` dan field media berisi path-nya:

```json theme={null}
{
  "image": "statics/media/1752404751-ad9e37ac-c658-4fe5-8d25-ba4a3f4d58fd.jpeg"
}
```

Jika ada keterangan, field berubah menjadi `{"path": "...", "caption": "..."}` dan keterangannya juga berada di `body`. Jika unduhan otomatis dinonaktifkan, nilainya adalah `{"url": "https://mmg.whatsapp.net/...", "caption": "..."}`; ambil file nanti dengan `GET /message/{message_id}/download?phone=<chat>`.

Katalog payload lengkap (polling, lokasi, kontak, sekali lihat, rujukan iklan, dan lainnya) tersedia di [referensi payload webhook](https://github.com/aldinokemal/go-whatsapp-web-multidevice/blob/main/docs/webhook-payload.md) upstream.

## Album dan pesan terstruktur

Album diterima sebagai beberapa event `message`. Header tidak memiliki isi pesan dan menyertakan jumlah item yang diharapkan:

```json theme={null}
{
  "id": "ALBUM_HEADER_ID",
  "album": {
    "expected_image_count": 3,
    "expected_video_count": 1
  }
}
```

Setiap foto atau video diterima sebagai event media biasa tersendiri dengan `album_id: "ALBUM_HEADER_ID"`. Kelompokkan item berdasarkan ID tersebut. Header bukan item media yang dapat diunduh dan tidak diteruskan ke Chatwoot.

Pembuatan polling, pemberian suara, pengeditan, dan penambahan opsi juga menggunakan `message`. Periksa objek `poll` terstruktur alih-alih hanya mengandalkan `body`. Hash opsi adalah hash SHA-256 heksadesimal huruf kecil dari nama opsi yang persis sama. Langganan `WHATSAPP_WEBHOOK_EVENTS=message` yang sudah ada menerima interaksi ini.

## Presence online dan offline

Berlangganan untuk setiap kontak individual menggunakan perangkat yang sama dengan penerima event:

```bash theme={null}
curl -u admin:changeme -X POST http://localhost:3000/user/presence/subscribe \
  -H "X-Device-Id: sales" \
  -H "Content-Type: application/json" \
  -d '{"phone":"628987654321"}'
```

Respons berhasil berisi `results.subscribed: true` dan `results.jid`. JID grup dan newsletter ditolak. Langganan tidak menggantikan pengaturan presence perangkat Anda. Untuk pembaruan terus-menerus, jalankan GOWA dengan:

```bash theme={null}
WHATSAPP_PRESENCE_ON_CONNECT=available
WHATSAPP_PRESENCE_PULSE_ENABLED=false
WHATSAPP_WEBHOOK_EVENTS=message,presence
```

Pulse presence default diakhiri dengan menandai perangkat sebagai tidak tersedia, sehingga pembaruan presence kontak berhenti. Menandai perangkat sebagai tersedia akan menonaktifkan notifikasi push WhatsApp di ponsel selama status tersebut aktif. Pertimbangkan konsekuensi ini sebelum mengaktifkan pemantauan terus-menerus.

```json theme={null}
{
  "event": "presence",
  "device_id": "628123456789@s.whatsapp.net",
  "timestamp": "2026-10-29T12:05:00Z",
  "payload": {
    "from": "628987654321@s.whatsapp.net",
    "state": "unavailable",
    "last_seen": "2026-10-29T12:04:35Z"
  }
}
```

`state` bernilai `available` atau `unavailable`. `last_seen` tidak disertakan jika tidak diketahui atau disembunyikan oleh pengaturan privasi kontak. `from_lid` disertakan jika berlaku. Aktivitas mengetik dan merekam tetap menggunakan event `chat_presence` terpisah dan tidak menggunakan langganan ini.

## Perubahan nama grup

```json theme={null}
{
  "event": "group.info",
  "device_id": "628123456789@s.whatsapp.net",
  "timestamp": "2026-10-29T10:35:00Z",
  "payload": {
    "chat_id": "120363402106000000@g.us",
    "name": "Project team",
    "name_set_by": "628987654321@s.whatsapp.net"
  }
}
```

`name_set_by` dikonversi dari LID ke JID nomor telepon jika memungkinkan dan tidak disertakan jika WhatsApp tidak mengidentifikasi pelakunya. Berlangganan `group.info` secara eksplisit jika daftar event yang diizinkan mengecualikan event lain.

## Pembaruan penghitung newsletter

`newsletter.message` melaporkan penghitung secara langsung, bukan jaminan isi postingan baru. Setiap entri selalu menyertakan `server_id`. `message_id`, `type`, dan `timestamp` tidak disertakan jika WhatsApp tidak menyediakannya. Penghitung yang bernilai nol atau tidak tersedia mungkin tidak disertakan.

```json theme={null}
{
  "event": "newsletter.message",
  "device_id": "628123456789@s.whatsapp.net",
  "timestamp": "2026-10-29T12:00:00Z",
  "payload": {
    "newsletter_id": "120363000000000000@newsletter",
    "messages": [
      {"server_id": 42, "views_count": 120, "forwards_count": 3}
    ]
  }
}
```

Jika tersedia, `reaction_counts` berisi jumlah reaksi dari WhatsApp. Proses pembaruan berdasarkan ID newsletter dan ID server. Jangan anggap penghitung yang tidak disertakan sebagai pengaturan ulang ke nol.

## Pembatasan akun dan logout

Event perangkat selalu menyertakan `session_id`, sehingga slot yang menggunakan nomor WhatsApp sama tetap dapat dibedakan. Event menggunakan konfigurasi webhook slot yang mengirimkannya. Logout jarak jauh mempertahankan slot agar dapat dipasangkan ulang dan melaporkan identitas sebelum logout. Pengaturan webhook slot tetap tersimpan setelah pemasangan ulang. Event ini tidak dikirim ke Chatwoot.

```json theme={null}
{
  "event": "device.logged_out",
  "device_id": "628123456789@s.whatsapp.net",
  "session_id": "sales",
  "timestamp": "2026-10-29T09:00:00Z",
  "payload": {
    "code": 401,
    "reason": "logged out from another device",
    "on_connect": true
  }
}
```

| Event | Field payload |
| - | - |
| `device.logged_out` | `code`, `reason`, `on_connect`. `on_connect` membedakan koneksi yang ditolak dari koneksi terbuka yang ditutup. |
| `device.temporary_ban` | `code`, `reason`, `expires_in_seconds`. `expires_at` adalah waktu berakhir dalam format RFC 3339 yang dihitung dan hanya muncul jika durasinya positif. Sesi tetap disimpan. |
| `device.reachout_timelock` | `is_active`. Field opsional `enforcement_type` meneruskan nilai dari WhatsApp. Field opsional `ends_at` adalah waktu berakhir dalam format RFC 3339. `is_active: false` berarti WhatsApp telah mencabut pembatasan. |

Kode diteruskan tanpa perubahan dan teks alasan berasal dari whatsmeow. Kode yang tidak dikenal tetap diterima. Kode logout `403` dan `406` saja tidak menunjukkan penyebab pastinya. Durasi pemblokiran sementara bernilai nol berarti WhatsApp tidak memberikan waktu berakhir. Reach-out timelock membatasi dimulainya chat baru dan dapat menyebabkan error pengiriman 463.

## Memverifikasi tanda tangan

Setiap permintaan menyertakan `X-Hub-Signature-256: sha256=<hex>`, yaitu HMAC-SHA256 dari isi permintaan **mentah** dengan secret webhook sebagai kuncinya. Hitung berdasarkan byte yang diterima secara persis, sebelum mem-parsing JSON.

```javascript Node.js (Express) theme={null}
const express = require("express");
const crypto = require("crypto");
const app = express();
const SECRET = process.env.WEBHOOK_SECRET;

app.post("/wa-hook", express.raw({ type: "application/json" }), (req, res) => {
  const expected = crypto.createHmac("sha256", SECRET).update(req.body).digest("hex");
  const signature = req.get("X-Hub-Signature-256") || "";
  if (!/^sha256=[0-9a-f]{64}$/.test(signature)) return res.sendStatus(401);
  const received = signature.slice(7);
  if (received.length !== expected.length ||
      !crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(received))) {
    return res.sendStatus(401);
  }
  const evt = JSON.parse(req.body);
  res.sendStatus(200);            // acknowledge fast
  handle(evt);                    // then process
});
```

```python Python (Flask) theme={null}
import hmac, hashlib, os
from flask import Flask, request, abort

app = Flask(__name__)
SECRET = os.environ["WEBHOOK_SECRET"].encode()

@app.post("/wa-hook")
def wa_hook():
    raw = request.get_data()
    expected = hmac.new(SECRET, raw, hashlib.sha256).hexdigest()
    received = request.headers.get("X-Hub-Signature-256", "").removeprefix("sha256=")
    if not hmac.compare_digest(expected, received):
        abort(401)
    evt = request.get_json()
    # enqueue evt for processing
    return "", 200
```

```go Go theme={null}
func waHook(w http.ResponseWriter, r *http.Request) {
	raw, _ := io.ReadAll(r.Body)
	mac := hmac.New(sha256.New, []byte(os.Getenv("WEBHOOK_SECRET")))
	mac.Write(raw)
	expected := hex.EncodeToString(mac.Sum(nil))
	received := strings.TrimPrefix(r.Header.Get("X-Hub-Signature-256"), "sha256=")
	if !hmac.Equal([]byte(expected), []byte(received)) {
		http.Error(w, "bad signature", http.StatusUnauthorized)
		return
	}
	w.WriteHeader(http.StatusOK)
	// process raw asynchronously
}
```

## Pengiriman dan percobaan ulang

* Setiap percobaan memiliki batas waktu **10 detik**.
* Respons non-2xx atau error jaringan akan dicoba ulang. GOWA melakukan hingga **5 percobaan**, dengan jeda 1 dtk, 2 dtk, 4 dtk, dan 8 dtk di antaranya. Tenggat konteks handler event dapat menghentikan pengiriman sebelum semua percobaan selesai.
* Setelah kegagalan terakhir, event dibuang dan dicatat di log. Tidak ada antrean persisten atau penyimpanan dead-letter.
* Pengiriman ke beberapa URL dilakukan secara independen.

Berikan respons `2xx` setelah menerima event ke dalam antrean pemrosesan persisten Anda sendiri. Buat handler yang idempoten karena event yang dicoba ulang dapat tiba lebih dari sekali.

## Tanda terima perangkat tertaut

Secara default, GOWA hanya meneruskan konfirmasi kontak dari perangkat utama untuk mengurangi duplikasi. Tanda terima `read` dan `read-self` milik akun saat ini tetap diteruskan dari semua perangkatnya. Untuk tanda terima milik akun sendiri ini, `payload.from` adalah JID akun dan `payload.ids` mengidentifikasi pesan masuk yang telah dibaca.

Tetapkan `WHATSAPP_WEBHOOK_ALL_DEVICE_RECEIPTS=true` atau `--webhook-all-device-receipts=true` agar juga menerima tanda terima kontak dari perangkat tertaut, termasuk saat ponsel kontak offline. Flag CLI menggantikan nilai dari environment, termasuk nilai `false` yang ditetapkan secara eksplisit.

Opsi ini dapat menghasilkan konfirmasi duplikat atau tidak berurutan. Terapkan pembaruan secara idempoten berdasarkan akun, chat, dan ID pesan. Jangan pernah menurunkan status pesan yang sudah dibaca menjadi terkirim saat tanda terima lama tiba. ID pesan dan JID pengirim mempertahankan bentuk kanonisnya tanpa akhiran perangkat.

## Memfilter event

**Berdasarkan jenis:** `WHATSAPP_WEBHOOK_EVENTS=message,message.ack` hanya meneruskan event tersebut.

**Berdasarkan chat atau pengirim:** `WHATSAPP_WEBHOOK_IGNORE_JIDS` mencocokkan `chat_id`, `from`, `chat_lid`, dan `from_lid`. Entri yang diawali `@` adalah wildcard untuk seluruh ruang alamat (`@g.us`, `@s.whatsapp.net`, `@lid`); entri lainnya harus cocok persis dengan JID.

```bash theme={null}
# drop all group traffic plus one specific contact
WHATSAPP_WEBHOOK_IGNORE_JIDS=@g.us,628123456789@s.whatsapp.net
```

`@s.whatsapp.net` juga cocok dengan pesan grup karena `from`-nya adalah JID pengguna. Gunakan `@g.us` untuk membisukan grup. Kedua filter diterapkan bersama: event hanya dikirim jika jenisnya diizinkan **dan** JID-nya tidak diabaikan.

## Webhook per perangkat

Berikan webhook, secret, dan daftar event yang diizinkan khusus untuk suatu slot:

```bash theme={null}
curl -u admin:changeme -X PATCH http://localhost:3000/devices/sales/webhook \
  -H "Content-Type: application/json" \
  -d '{
    "webhook_url": "https://sales.example.com/wa-hook",
    "webhook_secret": "sales-secret",
    "webhook_events": "message,message.ack",
    "webhook_insecure_skip_verify": false
  }'
```

Field yang sama juga diterima oleh `POST /devices`. Baca pengaturan saat ini dengan `GET /devices/{device_id}/webhook`. Kirim `"webhook_url": ""` untuk menghapusnya.

Jika `webhook_secret` atau `webhook_events` perangkat kosong, pengaturan global terkait akan digunakan. Nilai boolean `webhook_insecure_skip_verify` perangkat yang tersimpan menggantikan pengaturan TLS global. Secara khusus, `false` mempertahankan verifikasi sertifikat meskipun pengabaian verifikasi global diaktifkan.

```mermaid theme={null}
flowchart TD
    A[Event for a device] --> B{Device has its own webhook_url?}
    B -- No --> G[Send to global WHATSAPP_WEBHOOK URLs<br/>global secret and allowlist]
    B -- Yes --> C{WHATSAPP_WEBHOOK_DEVICE_MERGE_GLOBAL=true?}
    C -- No --> D[Send to device URL only<br/>device secret and allowlist]
    C -- Yes --> E[Send to device URL and global URLs<br/>each with its own secret and allowlist<br/>duplicate URLs receive the event once]
```

Secara default, URL per perangkat **menggantikan** `WHATSAPP_WEBHOOK` global untuk slot tersebut. Dengan `WHATSAPP_WEBHOOK_DEVICE_MERGE_GLOBAL=true`, URL tersebut **ditambahkan** ke URL global: URL perangkat menggunakan secret dan daftar event yang diizinkan milik perangkat, URL global tetap menggunakan pengaturan global, dan URL yang terdapat di keduanya menerima event satu kali. Aturan pengabaian JID berlaku untuk keduanya.

## Menguji secara lokal

Publikasikan penerima lokal melalui tunnel (misalnya `ngrok http 8080`) dan tetapkan `WHATSAPP_WEBHOOK` ke URL tunnel. Dengan `--debug=true`, GOWA mencatat setiap percobaan pengiriman dan kegagalan.

## Cara lain menerima event

* **[WebSocket](https://gowa-docs.mintlify.site/id/api-reference/websocket.md)** di `/ws?device_id=<id>` mengirim event pemasangan dan status ke klien dashboard. Gunakan webhook untuk pengiriman pesan.
* **Polling:** `GET /chats` dan `GET /chat/{chat_jid}/messages` membaca penyimpanan chat lokal GOWA. Lihat [Menerima pesan](https://gowa-docs.mintlify.site/id/examples/receiving-messages.md).


## Related topics

- [Endpoint webhook Chatwoot](https://gowa-docs.mintlify.site/id/api-reference/chatwoot/endpoint-webhook-chatwoot.md)
- [Setel konfigurasi webhook perangkat](https://gowa-docs.mintlify.site/id/api-reference/device/setel-konfigurasi-webhook-perangkat.md)
- [Ambil konfigurasi webhook perangkat](https://gowa-docs.mintlify.site/id/api-reference/device/ambil-konfigurasi-webhook-perangkat.md)
- [Endpoint webhook Chatwoot per perangkat](https://gowa-docs.mintlify.site/id/api-reference/chatwoot/endpoint-webhook-chatwoot-per-perangkat.md)
- [Referensi Konfigurasi](https://gowa-docs.mintlify.site/id/configuration.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.