Webhook WhatsApp
Terima pesan WhatsApp masuk dan status pengiriman (delivered/read) secara real-time ke server kamu lewat webhook device Dilztify.
Dokumentasi ini menjelaskan cara memakai fitur webhook device di Dilztify.
Overview
Webhook memungkinkan device mengirim event ke endpoint milikmu secara real-time.
Jika device kamu punya:
webhook_url- dan subscribe ke
webhook_events
maka setiap event yang terjadi akan dikirim ke URL tersebut.
Jika kamu mengisi webhook_token, setiap request juga akan menyertakan header signature untuk verifikasi keamanan.
Konsep Dasar
| Field | Fungsi |
|---|---|
webhook_url | Endpoint penerima event |
webhook_token | Token untuk signature (opsional) |
webhook_events | Daftar event yang di-subscribe |
Semua field bersifat opsional.
Field Reference
webhook_url
URL tujuan yang kamu pakai untuk menerima webhook.
https://client.example.com/webhooks/whatsappBehavior:
- Jika kosong → tidak ada request webhook yang dikirim
- Jika diisi → harus URL valid
webhook_token
Token rahasia yang kamu pakai untuk membuat signature.
Behavior:
- Jika diisi → header
x-signaturedikirim - Jika kosong → tidak ada signature
webhook_events
Daftar event yang ingin kamu terima di device ini.
["message", "message.ack", "group.participants"]Behavior:
- Hanya event yang disubscribe yang akan dikirim
- Jika kosong → tidak ada event yang dikirim
Create Device
{
"name": "Device A",
"phone": "628123456789",
"auto_read_personal": true,
"auto_read_group": false,
"webhook_url": "https://client.example.com/webhooks/whatsapp",
"webhook_token": "secret-device-token",
"webhook_events": ["message", "message.ack"]
}Update Device
{
"webhook_url": "https://client.example.com/webhooks/whatsapp",
"webhook_token": "secret-device-token",
"webhook_events": ["message.ack"]
}Event Example
message.ack
{
"event": "message.ack",
"device_id": "[email protected]",
"timestamp": "2025-07-18T22:44:20Z",
"payload": {
"ids": ["3EB00106E8BE0F407E88EC"],
"chat_id": "[email protected]",
"from": "[email protected]",
"from_lid": "251556368777322@lid",
"receipt_type": "delivered",
"receipt_type_description": "means the message was delivered to the device (but the user might not have noticed)."
}
}Signature Verification
Jika kamu mengisi webhook_token, setiap request akan membawa header:
x-signature: sha256=...Contoh Verifikasi (Node.js)
import crypto from 'crypto';
function verifyWebhookSignature(rawBody, signatureHeader, token) {
if (!token) return true;
if (!signatureHeader || !signatureHeader.startsWith('sha256=')) {
return false;
}
const expected = crypto
.createHmac('sha256', token)
.update(rawBody, 'utf8')
.digest('hex');
const received = signatureHeader.slice('sha256='.length);
return crypto.timingSafeEqual(
Buffer.from(expected, 'hex'),
Buffer.from(received, 'hex')
);
}Best Practices
- Simpan
webhook_tokendi server (jangan di frontend) - Gunakan HTTPS untuk
webhook_url - Respon webhook secepat mungkin (2xx)
- Buat handler idempotent (hindari efek duplikat)
- Proses hanya event yang disubscribe
- Boleh set
webhook_eventsdulu tanpawebhook_url
Important Notes
webhook_tokenbersifat opsional- Tanpa token → tidak ada
x-signature - Tanpa
webhook_url→ event tidak dikirim
Tips Integrasi
Untuk implementasi yang stabil:
- Gunakan queue (misalnya Redis / worker) untuk proses webhook
- Log semua request webhook (debugging)
- Terapkan retry mechanism jika endpoint gagal