Integrasi Webhook
1. Ikhtisar & Nilai Bisnis
Webhook DagangBot memungkinkan sistem eksternal Anda menerima notifikasi instan (event-driven) setiap kali terjadi aktivitas krusial di dalam platform. Alih-alih melakukan polling berkala yang membebani server dan API limit, DagangBot akan mendorong (push) muatan JSON ke endpoint HTTPS yang Anda tentukan segera setelah sebuah kejadian (event) terpicu.
Nilai Bisnis yang ditawarkan meliputi:
- Sinkronisasi Waktu Nyata: Pesanan baru, pembaruan status, dan pesan pelanggan langsung tersinkronisasi dengan ERP, CRM, atau sistem manajemen inventaris internal Anda.
- Efisiensi Sumber Daya: Menghilangkan kebutuhan polling API, mengurangi beban komputasi dan pemakaian bandwidth pada infrastruktur Anda.
- Otomatisasi Lanjutan: Memicu alur kerja (workflow) kustom di sistem Anda (misalnya: mencetak label pengiriman secara otomatis ketika webhook
order:newditerima). - Keamanan Tingkat Lanjut: Dilengkapi dengan tanda tangan HMAC-SHA256 untuk memverifikasi bahwa muatan benar-benar berasal dari infrastruktur DagangBot dan tidak dimanipulasi (Anti-Tampering).
2. Alur Visual & Antarmuka
Berikut adalah tampilan antarmuka pengaturan webhook pada dasbor merchant:



3. Panduan Langkah-demi-Langkah
Untuk mulai mendengarkan event dari DagangBot, Anda harus mendaftarkan URL endpoint Anda.
- Siapkan endpoint HTTPS pada server Anda yang dapat menerima metode
POSTdengan muatan JSON. Pastikan endpoint ini dapat merespons dalam waktu kurang dari 10 detik. - Masuk ke Dasbor Merchant DagangBot, navigasi ke menu Integrasi > Webhook.
- Klik tombol Tambah Webhook Baru.
- Masukkan URL endpoint Anda. Sistem mewajibkan penggunaan protokol
https://untuk lingkungan produksi guna menghindari penyadapan (Man-in-the-Middle attacks). Server dengan jaringan lokal atau loopback tidak diizinkan. - Sistem akan menghasilkan Secret Key acak (contoh: string heksadesimal 32 karakter). Simpan secret key ini di environment variables server Anda. Anda akan menggunakannya untuk memverifikasi tanda tangan HMAC.
- Pilih jenis event yang ingin didengarkan (misalnya: Pesan Masuk, Pesanan Baru).
- Klik Simpan & Uji. DagangBot akan mengirimkan event
pingke URL Anda. Pastikan endpoint Anda merespons dengan HTTP Status200 OKhingga299.
Pengaturan juga dapat dilakukan secara terprogram melalui API. Endpoint di bawah mengembalikan id integrasi.
Belum ada endpoint terdaftar untuk tag Integrations.
# Contoh mendaftarkan Webhook menggunakan cURL
curl -X POST https://dagangbot.web.id/api/v1/integrations/webhook \
-H "Authorization: Bearer <TOKEN>" \
-H "Content-Type: application/json" \
-d '{
"name": "ERP Webhook Sync",
"outbound_url": "https://erp.perusahaananda.com/api/webhook/dagangbot",
"events": ["chat:message", "order:new", "order:updated"],
"secret_key": "whsec_rahasia_perusahaan_anda"
}'4. Parameter & Spesifikasi Teknis
Ketika sebuah event terjadi, DagangBot melakukan HTTP POST ke endpoint Anda. Muatan dikirimkan dengan tipe konten application/json.
Header HTTP
Setiap permintaan webhook menyertakan header keamanan dan identifikasi berikut:
Kebijakan Pengiriman (Delivery Policy) & Fire-and-Forget
DagangBot menggunakan pendekatan pengiriman Fire-and-Forget (tanpa percobaan ulang otomatis) secara disengaja untuk Webhook Outbound. Keputusan arsitektur ini diambil guna menjamin urutan penerimaan kejadian secara ketat (Strict Ordering) dan mencegah terjadinya eksekusi ganda pada sistem konsumen (misalnya, menagih pembayaran pelanggan dua kali karena webhook yang dikirim ulang).
- Timeout Permintaan (10 Detik) & SSRF Guard: Setiap permintaan HTTP memiliki batas waktu tunggu (timeout) maksimum sebesar 10 detik dan diamankan dari serangan ke jaringan internal (SSRF guard), yang dikelola oleh modul
netguard.SafeHTTPClient(10*time.Second)DagangBot. Apabila server Anda gagal membalas dalam jeda ini, pengiriman langsung diputuskan dan dicatat sebagai gagal (Status Code 0). - Nihil Percobaan Ulang (0 Retry): Sistem tidak mengantrekan ulang muatan (payload) jika server Anda merespons dengan kesalahan
4xx,5xx, ataupun batas waktu terlampaui. - Log Pengiriman Transparan: Anda dapat melihat setiap percobaan pengiriman pada tabel
webhook_logsmelalui Dasbor Merchant. Ini mencakup muatan yang dikirim, durasi respons (Response Time dalam milidetik), kode status HTTP, dan kesalahan network jika ada. - Strategi Mitigasi: Kami menyarankan Anda untuk merancang endpoint Anda se-ringan mungkin. Terima request, validasi HMAC, tempatkan payload ke dalam antrean lokal Anda (seperti RabbitMQ, Redis, atau Kafka), dan segera kembalikan status
200 OK. Hindari pemrosesan berat (seperti pembuatan PDF atau query basis data yang lama) pada siklus penerimaan HTTP secara sinkron.
Penanganan Duplikat (Idempotency)
Meskipun DagangBot tidak melakukan retry otomatis pada tingkat network, retry dari tingkat aplikasi pengguna (misalnya, agen yang menekan tombol sinkronisasi ulang) dapat memicu pengiriman event yang sama lebih dari satu kali.
Setiap request yang dikirim menyertakan header X-DagangBot-Delivery yang berisi identifikasi unik pengiriman (contoh: del_17a4b9f2). Anda dapat menggunakan pengenal ini sebagai kunci idempotensi (Idempotency Key) di database Anda untuk menolak duplikat. Selain itu, pada event transaksional, selalulah bergantung pada referensi state akhir, seperti memvalidasi kolom status pesanan pada sistem Anda sebelum mengeksekusi operasi lanjutan.
Katalog Event dan Muatan (Payload)
Berikut adalah struktur muatan dari setiap kejadian yang dikirim oleh sistem (Payload event). Pembungkus (wrapper) standar untuk setiap event selalu memiliki struktur berikut:
{
"event": "nama_event",
"event_id": "del_169b8d7a123f",
"timestamp": "2026-10-08T10:00:00Z",
"merchant_id": "00000000-0000-0000-0000-000000000000",
"payload": { ... },
"data": { ... }
}Catatan: Kolom data dan payload merupakan duplikat satu sama lain untuk alasan kompatibilitas terbelakang. Anda dapat menggunakan salah satunya.
1. Event: chat:message
Terpicu saat terdapat pesan teks maupun media yang dikirim oleh pelanggan ke nomor WhatsApp Anda, ataupun ketika agen/sistem DagangBot membalas pesan tersebut.
Struktur payload:
2. Event: order:new
Terpicu saat pelanggan berhasil menyelesaikan proses pembuatan pesanan baru (Checkout) dari katalog atau bot pesanan. Notifikasi ini sangat berguna untuk sinkronisasi seketika ke dalam modul manajemen gudang (Warehouse Management System).
Struktur payload:
3. Event: order:updated
Terpicu jika ada perubahan pada objek pesanan secara menyeluruh akibat intervensi agen, sistem otomatis, perubahan alamat, pemutakhiran nomor resi pengiriman, hingga perubahan status selain pelunasan. Anda dapat menggunakan event ini untuk merekam histori audit siklus hidup pesanan di dalam CRM Anda.
Struktur muatan (payload) untuk order:updated identik dengan order:new, dengan tambahan field spesifik yang berubah, sehingga Anda selalu menerima gambaran mutakhir (snapshot) dari keseluruhan rekaman pesanan pada momen terjadinya perubahan tersebut.
4. Event: order:paid
Terpicu secara khusus saat gerbang pembayaran (Payment Gateway seperti Midtrans atau Xendit) mengirimkan webhook settlement yang mengonfirmasi bahwa dana transaksi telah berhasil dipotong dan terverifikasi, atau ketika agen mengonfirmasi pembayaran secara manual. Event ini adalah pemicu utama (Trigger) yang disarankan untuk mengeksekusi layanan pemenuhan (Fulfillment) atau pengurangan stok.
Struktur payload:
Verifikasi Keamanan HMAC-SHA256
Untuk memastikan bahwa permintaan benar-benar dikirim oleh server DagangBot dan tidak mengalami manipulasi di jalur komunikasi jaringan (Anti-Tampering/Man-in-the-Middle), Anda wajib memverifikasi header X-Signature. Nilai ini adalah hasil hash kriptografis HMAC-SHA256 dari seluruh deret byte raw body permintaan, ditandatangani menggunakan nilai Secret Key yang muncul saat Anda membuat pengaturan webhook. Selain X-Signature, secret key Anda juga disisipkan secara opsional di dalam header X-Webhook-Secret, X-Secret-Key, serta sebagai Authorization: Bearer <secret>.
// Contoh Verifikasi HMAC di Node.js (Express Framework)
const crypto = require('crypto');
const express = require('express');
const app = express();
const WEBHOOK_SECRET = process.env.DAGANGBOT_WEBHOOK_SECRET;
// Gunakan middleware body-parser raw untuk mempertahankan bentuk byte asli secara presisi.
// Memparsing ke dalam JSON sebelum verifikasi berisiko mengubah urutan kunci atau spasial,
// yang akan menyebabkan kegagalan pencocokan hash.
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
const signature = req.headers['x-signature'];
const payload = req.body;
// Buat hash lokal berdasarkan rahasia dan raw body yang diterima
const hash = crypto.createHmac('sha256', WEBHOOK_SECRET)
.update(payload)
.digest('hex');
// Bandingkan secara aman menggunakan timingSafeEqual untuk mencegah Side-Channel Attacks
// akibat perbedaan waktu komputasi dari proses pembandingan string biasa.
if (crypto.timingSafeEqual(Buffer.from(hash), Buffer.from(signature))) {
console.log("Verifikasi berhasil. Muatan event dipercaya dan valid.");
// Parse manual menjadi JSON setelah divalidasi
const eventData = JSON.parse(payload.toString());
// Eksekusi logika bisnis secara asinkron lalu berikan respons 200 OK dengan cepat.
processEventAsync(eventData);
res.status(200).send('OK');
} else {
console.error("Tanda tangan HMAC tidak valid! Menolak payload dengan status HTTP 401.");
res.status(401).send('Unauthorized Signature');
}
});
function processEventAsync(data) {
// Simpan ke antrean atau database backend
}Kebijakan Percobaan Ulang (Retry) dan Transmisi Event
Berbeda dengan sistem internal DagangBot yang memiliki antrean Outbox untuk sinkronisasi WebSocket, mekanisme Webhook Outbound DagangBot didesain murni sebagai transmisi asinkron tanpa antrean Dead-Letter (DLQ) dan tanpa penjadwalan backoff (No Retry Backoff).
Keputusan arsitektur ini didasarkan pada prinsip Strict Ordering (urutan ketat). Jika sebuah event order:new gagal terkirim dan dimasukkan ke dalam antrean percobaan ulang (retry queue), sementara event order:paid untuk pesanan yang sama berhasil terkirim sepersekian detik kemudian, sistem konsumen Anda akan memproses status paid sebelum new muncul. Kondisi balapan (Race Condition) ini akan menghancurkan konsistensi basis data pada ERP Anda.
Sebagai gantinya, mitigasi dilakukan melalui dua pilar:
- Log Transparan: Seluruh upaya transmisi (berhasil maupun gagal) direkam secara permanen dalam catatan log audit webhook. Anda bisa mengaudit parameter seperti durasi penyelesaian, Payload asli, dan Kode Error secara presisi.
- Pull Mandiri (Sinkronisasi Aktif): Jika server Anda mengalami pemutusan massal (Downtime), alih-alih mengandalkan Webhook Retry yang mungkin sudah kadaluwarsa, klien Anda dapat memanggil endpoint All-in-One API untuk melakukan penarikan (Pull) rekapitulasi data terakhir secara berurutan.
Rahasia Per-Endpoint (Per-Endpoint Secret Key)
Setiap endpoint URL yang diregistrasikan oleh penyewa memiliki kunci rahasia (Secret Key) masing-masing, yang dihasilkan secara kriptografis aman. Skema rahasia tunggal (satu kunci untuk semua URL) tidak digunakan demi mempersempit permukaan serangan (Attack Surface).
Tanda tangan HMAC-SHA256 divalidasi dengan mengambil kunci rahasia dari tabel integrations (kolom secret_key pada payload config) sesuai dengan integration_id yang sedang melakukan transmisi keluar.
Endpoint Uji dan Kirim Ulang (Ping Endpoint)
DagangBot menyediakan endpoint khusus untuk menguji konektivitas (Ping) tanpa perlu menunggu sebuah transaksi organik terjadi:
# Uji konektivitas webhook (Ping) secara manual
curl -X POST https://dagangbot.web.id/api/v1/integrations/webhook/{integration_id}/sync \
-H "Authorization: Bearer <TOKEN>"Pemanggilan ke /sync ini akan memaksa layanan ConnectorService.SyncWebhook untuk merakit sebuah event bertipe ping ("DagangBot Webhook Probe"). Respons akan mengembalikan durasi waktu tempuh (Round Trip Time), status HTTP dari server Anda, dan jejak respon teks (Response Body). Ini berfungsi layaknya radar (Sonar) untuk memastikan Load Balancer atau penyaring paket (Packet Filter) Anda tidak memblokir muatan DagangBot.
5. Relasi & Integrasi
Subsistem webhook ini berelasi kuat dengan berbagai fitur dalam infrastruktur DagangBot:
- All-in-One API: Walaupun webhook ini (Outbound) mendorong kejadian dari DagangBot ke server Anda, Anda dapat memadukannya dengan All-in-One API (Inbound) untuk membuat closed-loop system. Misalnya, Anda menerima notifikasi
chat:messagedari webhook, kemudian menggunakan All-in-One API untuk membalas pesan tersebut dari ERP internal Anda. - E-Commerce Sync: Saat webhook
order:updatedmengindikasikan pembayaran sukses (PAID), sistem sinkronisasi E-Commerce dapat dikoordinasikan di sisi server Anda untuk secara otomatis mengurangi stok pada platform toko yang berbeda secara bersamaan.
6. Pemecahan Masalah
Jika aliran data webhook Anda terlihat terhenti, tidak beroperasi, atau muatan data gagal tersampaikan ke tujuan akhir, ikuti panduan investigasi berikut:
1. Periksa Log Pengiriman (Webhook Logs)
Masuk ke Dasbor Merchant Anda, buka menu Integrasi, dan pilih sub-menu Log Webhook (Tabel webhook_logs). Modul ini adalah sumber kebenaran utama (Single Source of Truth) untuk mendiagnosis pengiriman. Anda akan menemukan catatan lengkap untuk setiap event yang dipicu, mencakup:
- Muatan Asli (Payload) yang coba dikirim.
- Waktu Respons (Response Time) yang dibutuhkan server Anda untuk menjawab (dalam milidetik).
- HTTP Status Code aktual yang diterima (contoh: 200, 401, 502, atau 0 untuk kegagalan jaringan fatal).
- Pesan Kesalahan Jaringan (Error Traces) jika terjadi pemutusan koneksi di tingkat TCP atau SSL/TLS (Handshake timeout).
2. Evaluasi Perlindungan SSRF (Server-Side Request Forgery)
Demi alasan keamanan platform dan kepatuhan standar industri (Compliance), Safe HTTP Client DagangBot dilengkapi pengamanan proaktif terhadap eksploitasi SSRF. Apabila log menunjukkan error pemblokiran saat Anda menyimpan URL, pastikan URL tujuan Anda memenuhi kriteria berikut:
- Dilarang Menggunakan Alamat Lokal: Menyematkan endpoint dengan alamat jaringan internal seperti
127.0.0.1,localhost,0.0.0.0, atau merujuk ke blok jaringan privat (10.0.x.x,172.16.x.x, dan192.168.x.x) akan secara tegas ditolak. - Wajib Menggunakan HTTPS: Protokol
http://usang tidak akan dilayani pada lingkungan produksi untuk mencegah serangan pencegatan (Man-in-the-Middle / Packet Sniffing). - Fase Pengembangan Lokal: Ketika Anda masih mengembangkan aplikasi secara lokal (Localhost), wajib gunakan utilitas Tunneling publik seperti Ngrok, Cloudflare Tunnels, atau Expose. URL publik yang dihasilkan oleh alat-alat ini akan diizinkan oleh subsistem Safe HTTP Client kami.
3. Mengidentifikasi Penyebab Timeout
Batas toleransi penantian (timeout limit) HTTP dari DagangBot adalah 10 detik. Jika rata-rata metrik Response Time di log Anda mendekati 10.000 ms, ini adalah indikator bahwa endpoint Anda melampaui batas kewajaran operasional. Solusi Praktis:
- Pindahkan Pemrosesan ke Background: Jangan merender faktur PDF PDF, tidak melakukan kueri berat ke database analitik, atau menunggu proses pengiriman email ke pelanggan secara sinkron di dalam controller HTTP Webhook Anda.
- Respons Cepat: Tulis program Anda untuk menerima muatan jaringan, simpan data ke Message Queue terdistribusi (seperti RabbitMQ, Apache Kafka, atau AWS SQS) atau tabel Staging di database SQL Anda, lalu segera balas request HTTP dengan
200 OK. Proses muatan tersebut pada worker terpisah secara asinkron (Asynchronous processing).
4. Resinkronisasi dan Uji Ulang Jaringan
Terdapat tombol Sinkronisasi (Ping) pada panel konfigurasi webhook. Tombol ini berguna untuk mengirimkan sinyal pelacak uji (Probe) tiruan untuk memastikan konektivitas antara jaringan infrastruktur DagangBot dan infrastruktur penyeimbang beban (Load Balancer) pada Cloud Provider Anda tidak terhalang oleh Firewall atau WAF (Web Application Firewall).
7. Kode Error & Penanganan
Di dalam panel riwayat Log Webhook, Anda mungkin akan menemui variasi indikasi error atau kode status HTTP (HTTP Status Codes) yang ditangkap oleh peladen DagangBot dari server Anda. Berikut adalah makna teknis dan cara menanganinya:
