Konfigurasi Webhook & Verifikasi

Webhook mengizinkan Kirem untuk mengirimkan data secara real-time ke server Anda (seperti ketika ada pesan masuk dari pelanggan, atau perubahan status pengiriman pesan).

🚦 1. Manajemen Aturan Webhook via API

Anda dapat mendaftarkan satu atau beberapa aturan pengiriman webhook (Webhook Rules) secara dinamis.

A. Mendapatkan Daftar Aturan Webhook

GET /v1/webhooks

• Headers: Authorization: Bearer <API_KEY>

B. Membuat Aturan Webhook Baru

POST /v1/webhooks

• Request Body (JSON):

{
  "url": "https://api.yourdomain.com/webhooks/kirem",
  "events": ["messages.received", "messages.status"],
  "conditions": {
    "channel_id": "chan-123"
  }
}

• Respons Sukses (201 Created):

{
  "status": 201,
  "message": "Webhook rule created successfully",
  "data": {
    "id": "web-rule-889932",
    "url": "https://api.yourdomain.com/webhooks/kirem",
    "secret_key": "whsec_0a7b8e...",
    "is_active": true,
    "events": ["messages.received", "messages.status"],
    "conditions": {
      "channel_id": "chan-123"
    }
  }
}

🔒 2. Validasi Tanda Tangan Webhook (HMAC SHA-256)

Untuk memastikan bahwa webhook benar-benar dikirim oleh Kirem dan isinya tidak dimodifikasi di tengah jalan, Kirem menyertakan header tanda tangan X-Signature pada setiap request.

Format Header X-Signature:

X-Signature: t=1719391000,v1=9f82d2ea7b4e3c98d6c7...

• t: Unix timestamp saat payload dikirim.
• v1: Tanda tangan HMAC-SHA256 dari payload.

Cara Menghitung & Memverifikasi Tanda Tangan (Sisi Server Anda):

1. Ekstrak nilai t (timestamp) dan v1 (tanda tangan) dari header X-Signature.
2. Bentuk string pesan (signature message) dengan menggabungkan timestamp, karakter titik (.), dan isi mentah JSON body (raw payload):

   message = timestamp + "." + raw_payload_body
   

3. Hitung kode HMAC-SHA256 dari string message tersebut menggunakan secret_key webhook Anda (didapatkan saat membuat aturan webhook, contoh: whsec_xxx).
4. Bandingkan hasil perhitungan (dalam format hex) dengan nilai v1 secara aman (constant time comparison).
5. Pencegahan Replay Attack: Pastikan selisih antara timestamp t dengan waktu server Anda saat ini tidak melebihi batas toleransi yang wajar (direkomendasikan maksimal 5 menit atau 300 detik).

📦 3. Format Payload Webhook Callback

Event: messages.received (Pesan Masuk dari Pelanggan)

{
  "event": "messages.received",
  "project_id": "proj-123",
  "channel_id": "chan-123",
  "data": {
    "from": "62812345678",
    "message_id": "wamid.HBgLNjI4MTIzNDU2NzhGFgQ0NDMzMzc3RUQ1OEFG",
    "timestamp": 1719391000,
    "type": "text",
    "text": {
      "body": "Halo, saya ingin bertanya tentang produk Anda."
    }
  }
}