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

# Konfigurasi Webhook

> Siapkan dan konfigurasi webhook

## Menyiapkan Webhook Anda

<Steps>
  <Step title="Akses Dashboard">
    Login ke dashboard CSKU AI Anda
  </Step>

  <Step title="Navigasi ke Pengaturan">
    Buka Settings → Webhook
  </Step>

  <Step title="Masukkan URL">
    Input URL webhook Anda yang dapat diakses publik
  </Step>

  <Step title="Generate Secret">
    Generate atau masukkan secret key Anda untuk autentikasi
  </Step>

  <Step title="Simpan Konfigurasi">
    Klik simpan untuk mengaktifkan webhook
  </Step>
</Steps>

<Callout type="info">
  Perubahan pada konfigurasi webhook berlaku segera.
</Callout>

## Prasyarat

Sebelum mengkonfigurasi webhook, pastikan Anda memiliki:

<AccordionGroup>
  <Accordion title="Endpoint Publik">
    URL webhook Anda harus dapat diakses publik dari internet. URL localhost tidak akan berfungsi untuk produksi.
  </Accordion>

  <Accordion title="HTTPS di Produksi">
    Gunakan HTTPS untuk lingkungan produksi. HTTP hanya dapat diterima untuk pengujian.
  </Accordion>

  <Accordion title="Kapasitas Server">
    Pastikan server Anda dapat menangani volume webhook yang diharapkan.
  </Accordion>
</AccordionGroup>

## Menguji Webhook Anda

Sebelum mengaktifkan webhook untuk produksi, uji endpoint Anda:

### 1. Pengujian Lokal dengan ngrok

```bash theme={null}
# Install ngrok
brew install ngrok  # macOS
# atau download dari https://ngrok.com

# Jalankan server lokal Anda
node server.js  # Aplikasi Anda mendengarkan di port 3000

# Buat tunnel
ngrok http 3000

# Anda akan mendapatkan URL seperti: https://abc123.ngrok.io
```

<Note>
  Gunakan URL ngrok untuk menguji webhook Anda secara lokal sebelum deploy.
</Note>

### 2. Uji dengan curl

```bash theme={null}
curl -X POST https://your-webhook-url.com/webhook \
  -H "Authorization: your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "channel.message_in",
    "timestamp": 1738056000,
    "conversation_id": "conv_test123",
    "conversation_label": "Test User",
    "need_human": 0,
    "message": {
      "id": "msg_test456",
      "sender_name": "Test User",
      "channel": {
        "id": "channel_test",
        "name": "WhatsApp Business",
        "engine": "wa"
      },
      "bisnis": {
        "id": "biz_test",
        "name": "Test Business"
      },
      "user": {
        "id": "merchant_test",
        "name": "Test Merchant"
      },
      "content": {
        "type": "text",
        "text": "Test message"
      }
    }
  }'
```

### 3. Uji dengan Tool Pengujian Webhook

Gunakan layanan seperti:

* [Webhook.site](https://webhook.site) - Pengujian cepat tanpa server
* [RequestBin.com](https://requestbin.com) - Inspeksi request webhook
* [Webhook Tester](https://webhooktester.com) - Pengujian real-time

## Field Konfigurasi

### URL Webhook

Endpoint Anda yang akan menerima request POST.

<Callout type="warning">
  Harus dimulai dengan `https://` untuk produksi. `http://` hanya untuk pengujian.
</Callout>

**Contoh:**

* ✅ Valid: `https://api.yourdomain.com/webhooks/csku`
* ✅ Valid: `https://abc123.ngrok.io/webhook` (pengujian)
* ❌ Tidak Valid: `http://api.yourdomain.com/webhook` (produksi)
* ❌ Tidak Valid: `http://localhost:3000/webhook` (tidak publik)

### Secret Key

Digunakan untuk mengautentikasi request webhook.

**Praktik Terbaik:**

* Generate key yang kuat dan acak
* Simpan dengan aman (environment variables, secrets manager)
* Rotasi secara berkala
* Jangan bagikan secara publik

## Rekomendasi URL Webhook

### Struktur Path

Gunakan path yang jelas dan deskriptif:

```
✅ Bagus:
https://api.yourdomain.com/webhooks/csku
https://api.yourdomain.com/v1/webhooks
https://webhooks.yourdomain.com/ai

❌ Hindari:
https://api.yourdomain.com (endpoint root)
https://api.yourdomain.com/a/b/c/d/e (terlalu bersarang)
```

### Konfigurasi DNS

```bash theme={null}
# Tambahkan subdomain webhook
webhooks.yourdomain.com IN A 192.0.2.1

# Atau gunakan domain API yang ada
api.yourdomain.com IN A 192.0.2.1
```

### Sertifikat SSL

Pastikan endpoint webhook Anda memiliki sertifikat SSL yang valid:

```bash theme={null}
# Periksa sertifikat SSL
curl -I https://your-webhook-url.com/webhook

# Seharusnya menampilkan:
# SSL certificate verify ok.
```

## Konfigurasi Firewall dan Jaringan

### Aturan Firewall

Izinkan koneksi masuk dari server CSKU AI:

```bash theme={null}
# Contoh aturan firewall (sesuaikan dengan setup Anda)
ufw allow 443/tcp  # HTTPS
ufw allow 80/tcp   # HTTP (pengujian saja)
```

### Konfigurasi Load Balancer

Jika menggunakan load balancer:

```nginx theme={null}
# Contoh konfigurasi nginx
upstream webhook_servers {
    server 10.0.0.1:3000;
    server 10.0.0.2:3000;
    server 10.0.0.3:3000;
}

server {
    listen 443 ssl;
    server_name webhooks.yourdomain.com;
    
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;
    
    location /webhooks {
        proxy_pass http://webhook_servers;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_read_timeout 30s;
    }
}
```

## Contoh Konfigurasi

### Lingkungan Produksi

```json theme={null}
{
  "webhook_url": "https://api.yourdomain.com/v1/webhooks/csku",
  "secret_key": "prod_secret_abc123xyz",
  "enabled": true,
  "events": [
    "channel.message_in",
    "agent.message_out",
    "ai.message_generated",
    "device.connected",
    "device.disconnected"
  ]
}
```

### Lingkungan Staging

```json theme={null}
{
  "webhook_url": "https://staging-api.yourdomain.com/webhooks/csku",
  "secret_key": "staging_secret_def456abc",
  "enabled": true,
  "events": ["channel.message_in"]
}
```

### Lingkungan Development

```json theme={null}
{
  "webhook_url": "https://abc123.ngrok.io/webhook",
  "secret_key": "dev_secret_ghi789def",
  "enabled": true,
  "events": ["channel.message_in"]
}
```

## Monitoring Webhook Anda

### Monitoring Dashboard

Periksa dashboard CSKU AI Anda untuk:

* Status pengiriman webhook
* Percobaan pengiriman yang gagal
* Waktu respons
* Log error

### Log Server

Monitor endpoint webhook Anda:

```javascript theme={null}
// Log penerimaan webhook
app.post('/webhook', (req, res) => {
  const startTime = Date.now();
  
  logger.info('Webhook diterima', {
    event: req.body.event,
    timestamp: req.body.timestamp,
    ip: req.ip,
    userAgent: req.headers['user-agent']
  });
  
  // Proses webhook...
  
  const duration = Date.now() - startTime;
  logger.info('Webhook diproses', {
    duration: duration + 'ms',
    status: res.statusCode
  });
  
  res.status(200).send('OK');
});
```

## Praktik Terbaik

<AccordionGroup>
  <Accordion title="Gunakan HTTPS">
    Selalu gunakan HTTPS di produksi untuk mengenkripsi payload webhook.
  </Accordion>

  <Accordion title="Amankan Secret Key">
    Simpan secret key di environment variables, bukan di kode.
  </Accordion>

  <Accordion title="Uji Secara Menyeluruh">
    Uji dengan semua jenis event sebelum mengaktifkan di produksi.
  </Accordion>

  <Accordion title="Monitor Performa">
    Lacak waktu pemrosesan webhook dan tingkat error.
  </Accordion>

  <Accordion title="Miliki Fallback">
    Implementasikan penanganan error dan logging untuk webhook yang gagal.
  </Accordion>
</AccordionGroup>

## Troubleshooting

### Webhook Tidak Diterima

<Steps>
  <Step title="Periksa Dashboard">
    Verifikasi URL webhook dikonfigurasi dengan benar
  </Step>

  <Step title="Uji Endpoint">
    Gunakan curl atau tool pengujian webhook untuk memverifikasi aksesibilitas
  </Step>

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

  <Step title="Verifikasi Autentikasi">
    Pastikan secret key cocok persis
  </Step>
</Steps>

### Error 404

<Callout type="error">
  URL webhook Anda mengembalikan 404 Not Found.
</Callout>

**Solusi:**

* Verifikasi path URL benar
* Periksa apakah web server berjalan
* Pastikan port dapat diakses
* Tinjau aturan firewall

### Error Timeout

**Solusi:**

* Tingkatkan pengaturan timeout server Anda
* Optimalkan pemrosesan webhook
* Gunakan pemrosesan async untuk tugas berat
* Periksa konektivitas jaringan

## Langkah Selanjutnya

<CardGroup cols={2}>
  <Card title="Autentikasi" icon="lock" href="/webhooks/authentication">
    Amankan endpoint webhook Anda
  </Card>

  <Card title="Referensi Event" icon="zap" href="/webhooks/events/channel-message-in">
    Pelajari tentang jenis event
  </Card>

  <Card title="Praktik Terbaik" icon="check-circle" href="/webhooks/best-practices">
    Pastikan penanganan yang andal
  </Card>

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

## Dukungan

Butuh bantuan mengkonfigurasi webhook?

* Email: [support@csku.ai](mailto:support@csku.ai)
* Dashboard: [https://dashboard.csku.ai](https://dashboard.csku.ai)