Skip to main content

​
Masalah Umum

​
Webhook Tidak Diterima

Endpoint webhook tidak menerima event apapun.
Kemungkinan Penyebab:
  • URL ada typo
  • Menggunakan HTTP bukan HTTPS (produksi)
  • URL localhost bukan URL publik
  • Path salah
  • Webhook tidak diaktifkan di dashboard
  • Secret key tidak cocok
  • Web server tidak berjalan
  • Port yang salah diekspos
  • Firewall memblokir koneksi
  • Masalah resolusi DNS
Solusi:
1

Verifikasi Dashboard

Periksa URL webhook dikonfigurasi dengan benar di dashboard CSKU AI (app.csku.ai/settings/webhook-settings)
2

Uji Endpoint

Gunakan curl untuk menguji aksesibilitas webhook
3

Tinjau Log

Periksa log dashboard CSKU AI dan server Anda
4

Verifikasi Firewall

Pastikan port 443 (HTTPS) terbuka
Uji dengan curl: 
# Uji endpoint webhook
curl -X POST https://your-webhook-url.com/webhook \
  -H "Authorization: your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "test",
    "timestamp": 1738056000
  }'

# Seharusnya menerima: OK

​
Kegagalan Autentikasi

Gejala: Selalu menerima error 401 Solusi:
Verifikasi secret key Anda cocok persis dengan yang ada di dashboard (case-sensitive, tanpa whitespace)
Pastikan Anda memeriksa header Authorization (bukan authorization huruf kecil)
Trim whitespace dari secret yang disimpan dan header yang diterima
Log nilai yang diharapkan dan diterima untuk mengidentifikasi ketidakcocokan
Contoh debug: 
const SECRET_KEY = 'your_secret_key';

app.post('/webhook', (req, res) => {
  const authHeader = req.headers.authorization;
  
  // Debug logging (hapus di produksi!)
  console.log('Diharapkan:', JSON.stringify(SECRET_KEY));
  console.log('Diterima:', JSON.stringify(authHeader));
  console.log('Cocok:', authHeader === SECRET_KEY);
  
  if (authHeader !== SECRET_KEY) {
    console.error('Autentikasi gagal');
    return res.status(401).json({ error: 'Unauthorized' });
  }
  
  res.status(200).send('OK');
});

​
Event Duplikat

Gejala: Event yang sama diterima beberapa kali
Ini adalah perilaku yang diharapkan karena mekanisme retry.
Solusi: Implementasikan idempotensi menggunakan message ID 
const processedEvents = new Set();

app.post('/webhook', async (req, res) => {
  const { event, message } = req.body;
  const eventId = `${event}_${message.id}`;
  
  // Periksa apakah sudah diproses
  if (processedEvents.has(eventId)) {
    console.log('Event duplikat, melewati');
    return res.status(200).send('OK');
  }
  
  // Proses event
  await handleEvent(event, message);
  
  // Tandai sebagai sudah diproses
  processedEvents.add(eventId);
  
  res.status(200).send('OK');
});

​
Waktu Respons Lambat

Gejala: Webhook timeout atau terlalu lama Penyebab:
Melakukan terlalu banyak pekerjaan di handler webhook
Query lambat, masalah koneksi, kurang index
Panggilan API eksternal, jaringan lambat
Operasi sinkron memblokir respons
Solusi:
  1. Gunakan Pemrosesan Async
app.post('/webhook', async (req, res) => {
  // Acknowledge segera
  res.status(200).send('OK');
  
  // Proses di background
  setImmediate(async () => {
    await processWebhook(req.body);
  });
});
  1. Queue Tugas Berat
const Queue = require('bull');
const webhookQueue = new Queue('webhooks');

app.post('/webhook', async (req, res) => {
  // Tambahkan ke queue
  await webhookQueue.add(req.body);
  
  // Respons segera
  res.status(200).send('OK');
});

// Proses secara terpisah
webhookQueue.process(async (job) => {
  await processWebhook(job.data);
});
  1. Optimalkan Query Database
// Buruk: N+1 query
for (const msg of messages) {
  const user = await db.users.findById(msg.userId); // Query terpisah untuk setiap item
}

// Bagus: Single query dengan join
const messagesWithUsers = await db.messages.find({
  include: [{ model: db.users }]
});

​
Error 404 Not Found

Gejala: Endpoint webhook mengembalikan 404 Solusi:
Verifikasi path di dashboard cocok dengan route Anda (misal, /webhook vs /webhooks)
Pastikan route didefinisikan dengan benar di aplikasi Anda
Konfirmasi web server berjalan dan melayani port yang benar
Periksa apakah Anda menggunakan router yang mungkin mempengaruhi route
Contoh pemeriksaan route: 
// Express
app.post('/webhook', (req, res) => {
  res.status(200).send('OK');
});

// Verifikasi dengan curl
curl -X POST https://your-domain.com/webhook
# Seharusnya mengembalikan 200, bukan 404

​
Error Timeout

Gejala: Request webhook timeout Solusi:
Tingkatkan pengaturan timeout webhook di web server Anda
Kurangi waktu pemrosesan, gunakan operasi async
Pastikan CPU dan memory cukup
Periksa konektivitas jaringan dan latensi
Konfigurasi timeout Express: 
const express = require('express');
const app = express();

// Tingkatkan timeout
app.use(express.json({ limit: '10mb' }));
app.timeout = 30000; // 30 detik

app.post('/webhook', async (req, res) => {
  // Proses webhook...
  res.status(200).send('OK');
});

​
Masalah Rate Limiting

Gejala: Beberapa webhook diterima, yang lain terlewat Solusi:
Pastikan rate limit Anda wajar
Konfirmasi Anda tidak melebihi limit platform
Lacak tingkat pengiriman webhook
Implementasikan queueing jika pemrosesan lambat

​
Tips Debugging

​
Aktifkan Logging Verbose

const logger = require('morgan')('combined');
app.use(logger);

app.post('/webhook', async (req, res) => {
  console.log('=== Webhook Diterima ===');
  console.log('Headers:', JSON.stringify(req.headers, null, 2));
  console.log('Body:', JSON.stringify(req.body, null, 2));
  console.log('Timestamp:', new Date().toISOString());
  
  // Proses webhook...
  res.status(200).send('OK');
});

​
Gunakan Request Inspector

# Install ngrok untuk pengujian lokal
ngrok http 3000

# Gunakan URL ngrok di konfigurasi webhook
# Semua webhook akan terlihat di dashboard ngrok

​
Uji dengan Tool Berbeda

URL webhook sementara gratis untuk pengujian
Inspeksi request webhook secara real-time
Uji endpoint webhook secara manual
Pengujian dan debugging command-line

​
Checklist Monitoring

Gunakan checklist ini untuk memonitor kesehatan webhook.

​
Monitoring Pengiriman

  • Lacak tingkat keberhasilan pengiriman webhook
  • Monitor percobaan retry
  • Alert pada kegagalan berturut-turut
  • Periksa kegagalan permanen

​
Monitoring Performa

  • Ukur waktu respons (P50, P95, P99)
  • Monitor resource server (CPU, memory)
  • Lacak waktu query database
  • Perhatikan operasi lambat

​
Monitoring Error

  • Log semua error webhook
  • Kategorikan jenis error
  • Lacak tingkat error
  • Alert pada lonjakan error

​
Monitoring Integrasi

  • Verifikasi event diproses dengan benar
  • Periksa integritas data
  • Monitor sistem downstream
  • Validasi idempotensi

​
Kapan Menghubungi Support

Hubungi support ketika Anda sudah mencoba semua opsi troubleshooting.
Hubungi support jika:
  • Anda sudah memverifikasi endpoint Anda dapat diakses
  • Autentikasi dikonfigurasi dengan benar
  • Webhook masih tidak terkirim
  • Anda mengalami masalah yang persisten
Berikan detail ini saat menghubungi support:
  1. URL Webhook
  2. Event yang diharapkan vs. event yang diterima
  3. Screenshot dashboard (jika berlaku)
  4. Log server (disanitasi)
  5. Timestamp webhook sukses terakhir
  6. Langkah-langkah yang sudah Anda lakukan

​
Langkah Selanjutnya

Praktik Terbaik

Pastikan penanganan webhook yang andal

Contoh

Sampel kode implementasi