🚫 Anda tidak terhubung ke internet
Dokumentasi Web

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

FieldFungsi
webhook_urlEndpoint penerima event
webhook_tokenToken untuk signature (opsional)
webhook_eventsDaftar 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/whatsapp

Behavior:

  • 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-signature dikirim
  • 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": "628123456789@s.whatsapp.net",
  "timestamp": "2025-07-18T22:44:20Z",
  "payload": {
    "ids": ["3EB00106E8BE0F407E88EC"],
    "chat_id": "120363402106XXXXX@g.us",
    "from": "6289685XXXXXX@s.whatsapp.net",
    "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_token di 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_events dulu tanpa webhook_url

Important Notes

  • webhook_token bersifat 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

On this page