> ## Documentation Index
> Fetch the complete documentation index at: https://docs.csku.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting Webhook

> Debug dan perbaiki masalah webhook

## Masalah Umum

### Webhook Tidak Diterima

<Callout type="error">
  Endpoint webhook tidak menerima event apapun.
</Callout>

**Kemungkinan Penyebab:**

<AccordionGroup>
  <Accordion title="URL Webhook Salah">
    * URL ada typo
    * Menggunakan HTTP bukan HTTPS (produksi)
    * URL localhost bukan URL publik
    * Path salah
  </Accordion>

  <Accordion title="Masalah Konfigurasi">
    * Webhook tidak diaktifkan di dashboard
    * Secret key tidak cocok
  </Accordion>

  <Accordion title="Masalah Server">
    * Web server tidak berjalan
    * Port yang salah diekspos
    * Firewall memblokir koneksi
    * Masalah resolusi DNS
  </Accordion>
</AccordionGroup>

**Solusi:**

<Steps>
  <Step title="Verifikasi Dashboard">
    Periksa URL webhook dikonfigurasi dengan benar di dashboard CSKU AI ([app.csku.ai/settings/webhook-settings](https://app.csku.ai/settings/webhook-settings))
  </Step>

  <Step title="Uji Endpoint">
    Gunakan curl untuk menguji aksesibilitas webhook
  </Step>

  <Step title="Tinjau Log">
    Periksa log dashboard CSKU AI dan server Anda
  </Step>

  <Step title="Verifikasi Firewall">
    Pastikan port 443 (HTTPS) terbuka
  </Step>
</Steps>

**Uji dengan curl:**

```bash theme={null}
# 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:**

<AccordionGroup>
  <Accordion title="Periksa Secret Key">
    Verifikasi secret key Anda cocok persis dengan yang ada di dashboard (case-sensitive, tanpa whitespace)
  </Accordion>

  <Accordion title="Verifikasi Nama Header">
    Pastikan Anda memeriksa header `Authorization` (bukan `authorization` huruf kecil)
  </Accordion>

  <Accordion title="Hapus Whitespace">
    Trim whitespace dari secret yang disimpan dan header yang diterima
  </Accordion>

  <Accordion title="Debug Logging">
    Log nilai yang diharapkan dan diterima untuk mengidentifikasi ketidakcocokan
  </Accordion>
</AccordionGroup>

**Contoh debug:**

```javascript theme={null}
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

<Callout>
  Ini adalah perilaku yang diharapkan karena mekanisme retry.
</Callout>

**Solusi:** Implementasikan idempotensi menggunakan message ID

```javascript theme={null}
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:**

<AccordionGroup>
  <Accordion title="Pemrosesan Berat">
    Melakukan terlalu banyak pekerjaan di handler webhook
  </Accordion>

  <Accordion title="Masalah Database">
    Query lambat, masalah koneksi, kurang index
  </Accordion>

  <Accordion title="Latensi Jaringan">
    Panggilan API eksternal, jaringan lambat
  </Accordion>

  <Accordion title="Operasi Blocking">
    Operasi sinkron memblokir respons
  </Accordion>
</AccordionGroup>

**Solusi:**

1. **Gunakan Pemrosesan Async**

```javascript theme={null}
app.post('/webhook', async (req, res) => {
  // Acknowledge segera
  res.status(200).send('OK');
  
  // Proses di background
  setImmediate(async () => {
    await processWebhook(req.body);
  });
});
```

2. **Queue Tugas Berat**

```javascript theme={null}
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);
});
```

3. **Optimalkan Query Database**

```javascript theme={null}
// 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:**

<AccordionGroup>
  <Accordion title="Periksa Path URL">
    Verifikasi path di dashboard cocok dengan route Anda (misal, `/webhook` vs `/webhooks`)
  </Accordion>

  <Accordion title="Verifikasi Definisi Route">
    Pastikan route didefinisikan dengan benar di aplikasi Anda
  </Accordion>

  <Accordion title="Periksa Web Server">
    Konfirmasi web server berjalan dan melayani port yang benar
  </Accordion>

  <Accordion title="Tinjau Konfigurasi Router">
    Periksa apakah Anda menggunakan router yang mungkin mempengaruhi route
  </Accordion>
</AccordionGroup>

**Contoh pemeriksaan route:**

```javascript theme={null}
// 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:**

<AccordionGroup>
  <Accordion title="Tingkatkan Timeout">
    Tingkatkan pengaturan timeout webhook di web server Anda
  </Accordion>

  <Accordion title="Optimalkan Pemrosesan">
    Kurangi waktu pemrosesan, gunakan operasi async
  </Accordion>

  <Accordion title="Periksa Batas Resource">
    Pastikan CPU dan memory cukup
  </Accordion>

  <Accordion title="Masalah Jaringan">
    Periksa konektivitas jaringan dan latensi
  </Accordion>
</AccordionGroup>

**Konfigurasi timeout Express:**

```javascript theme={null}
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:**

<AccordionGroup>
  <Accordion title="Periksa Pengaturan Rate Limit">
    Pastikan rate limit Anda wajar
  </Accordion>

  <Accordion title="Tinjau Limit CSKU AI">
    Konfirmasi Anda tidak melebihi limit platform
  </Accordion>

  <Accordion title="Monitor Throughput">
    Lacak tingkat pengiriman webhook
  </Accordion>

  <Accordion title="Queue Event Masuk">
    Implementasikan queueing jika pemrosesan lambat
  </Accordion>
</AccordionGroup>

## Tips Debugging

### Aktifkan Logging Verbose

```javascript theme={null}
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

```bash theme={null}
# 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

<AccordionGroup>
  <Accordion title="Webhook.site">
    URL webhook sementara gratis untuk pengujian
  </Accordion>

  <Accordion title="RequestBin">
    Inspeksi request webhook secara real-time
  </Accordion>

  <Accordion title="Postman">
    Uji endpoint webhook secara manual
  </Accordion>

  <Accordion title="cURL">
    Pengujian dan debugging command-line
  </Accordion>
</AccordionGroup>

## Checklist Monitoring

<Callout>
  Gunakan checklist ini untuk memonitor kesehatan webhook.
</Callout>

### 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

<Callout type="info">
  Hubungi support ketika Anda sudah mencoba semua opsi troubleshooting.
</Callout>

**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

<CardGroup cols={1}>
  <Card title="Hubungi Support" icon="envelope" href="mailto:support@csku.ai">
    [support@csku.ai](mailto:support@csku.ai)
  </Card>
</CardGroup>

## Langkah Selanjutnya

<CardGroup cols={2}>
  <Card title="Praktik Terbaik" icon="check-circle" href="/webhooks/best-practices">
    Pastikan penanganan webhook yang andal
  </Card>

  <Card title="Contoh" icon="code" href="/webhooks/examples">
    Sampel kode implementasi
  </Card>
</CardGroup>