Copy page

Pengembang

Webhook

Konfigurasi webhook untuk menerima notifikasi real-time ketika peristiwa terjadi di organisasi Qwetty Anda.

Cara kerja webhook

Ketika peristiwa terjadi (misalnya, pesan baru masuk), Qwetty mengirim permintaan HTTP POST ke URL webhook yang telah dikonfigurasi beserta data peristiwa.

Menyiapkan webhook

1. Buka Pengaturan → Channel dan temukan bagian Webhook Settings
2. Klik Buat Webhook
3. Konfigurasi:
   • Name — Nama deskriptif
   • URL — Endpoint HTTPS Anda
   • Events — Peristiwa mana yang ingin diterima (pesan, pembaruan status, kontak, media)
   • Secret — Rahasia bersama untuk verifikasi tanda tangan HMAC
4. Simpan dan aktifkan

Jenis peristiwa

Qwetty saat ini mengirim peristiwa pesan:

Peristiwa	Deskripsi
message.incoming	Pesan diterima dari kontak
message.outgoing	Pesan dikirim dari organisasi Anda

Pengaturan webhook menampilkan tombol message, status, contact, dan media, tetapi hanya peristiwa pesan yang dikirim saat ini. Kunci toggle untuk kedua peristiwa di atas adalah message.

Payload webhook

Setiap pengiriman adalah body JSON dengan tepat tiga field:

Code
{
  "event": "message.incoming",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "data": { }
}

Pengiriman juga menyetel header X-Qwetty-Event dengan nama peristiwa. Tidak ada organizationId tingkat atas dalam payload.

Memverifikasi tanda tangan

Ketika webhook Anda memiliki secret, Qwetty menandatangani setiap pengiriman dengan HMAC-SHA256 atas body permintaan mentah (string JSON { event, timestamp, data } yang persis) dan mengirim digest hex dalam header X-Qwetty-Signature. Verifikasi terhadap body mentah — bukan objek yang diserialisasi ulang:

Code
const crypto = require('crypto');

// `rawBody` adalah string body permintaan yang persis dikirim Qwetty
function verifyWebhook(rawBody, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Pengujian lokal

Gunakan alat seperti ngrok untuk mengekspos server lokal Anda:

Code
ngrok http 3000

Kemudian gunakan URL ngrok sebagai endpoint webhook Anda selama pengembangan.

Praktik terbaik

• Selalu verifikasi tanda tangan untuk memastikan permintaan berasal dari Qwetty
• Respons dengan cepat — Qwetty menunggu hingga 10 detik untuk respons sebelum timeout
• Jangan mengandalkan percobaan ulang — Pengiriman bersifat fire-and-forget; kegagalan dicatat tetapi tidak dicoba ulang, jadi buat endpoint Anda tangguh
• Gunakan HTTPS — URL webhook harus menggunakan HTTPS di lingkungan produksi

Langkah selanjutnya

• Pengaturan Percakapan & Webhook — Tempat webhook dikonfigurasi
• Referensi API — Dokumentasi endpoint lengkap