Mengirim Event Escalation ke Webhook

Webhook memungkinkan qlar memberi tahu sistem Anda hampir secara real-time saat event escalation terjadi, misalnya untuk:

• Membuat atau memperbarui tiket di tool helpdesk Anda
• Memberi tahu channel Slack atau Teams
• Memicu alur kerja monitoring internal atau kepatuhan

Sebelum memulai

• Escalation sudah diaktifkan dan disimpan. Lihat Mengatur Escalation.
• Anda sudah menguji alur supervisor sekali. Lihat Menerima dan Mengelola Escalation.
• Anda punya endpoint HTTPS yang bisa menerima request uji dan menampilkan body serta header-nya.

Langkah 1: Buka Kartu Webhook di Setelan Escalation

Di CMS, buka Conversation → Escalation lalu gulir ke Webhook Notifications.

Catatan validasi:

• Pastikan kartu Webhook Notifications terlihat di halaman setelan Escalation yang sama tempat Anda mengatur perilaku escalation.
• Jika kartu tidak ada, pastikan Anda sedang mengedit agent/environment yang benar dan role Anda punya izin untuk memperbarui setelan escalation.

Langkah 2: Aktifkan Webhook

Geser toggle Webhook ke Enabled.

Setelah diaktifkan, kontrol webhook URL dan secret key akan terlihat.

Catatan validasi:

• Segera setelah mengaktifkan, periksa bahwa field Webhook URL dan Secret Key muncul.
• Jika tidak muncul, refresh sekali dan pastikan toggle masih menunjukkan Enabled sebelum melanjutkan.

Langkah 3: Atur Webhook URL

Masukkan endpoint Anda di Webhook URL.

Persyaratan:

• URL tidak boleh kosong
• URL harus diawali https://

Contoh:

https://your-domain.com/integrations/qlar/escalation

Catatan validasi:

• Pakai endpoint HTTPS kelas production yang bisa dijangkau dari internet (bukan localhost).
• Lakukan pengecekan cepat dari log backend atau API gateway Anda untuk memastikan request ke path ini diterima.
• Kembalikan error non-2xx yang jelas untuk method yang tidak didukung, agar masalah integrasi lebih mudah didiagnosis.

Langkah 4: Salin dan Amankan Secret Key

Pakai tombol copy di Secret Key untuk menyimpan key secara aman di secret manager backend Anda.

Jangan tampilkan key ini di kode frontend atau log publik.

Catatan validasi:

• Simpan key di secret store yang aman (misalnya secret manager environment atau vault), bukan di source control.
• Pastikan layanan penerima Anda bisa membaca key yang tersimpan saat runtime.
• Samarkan key di log dan dashboard untuk mencegah kebocoran yang tidak disengaja.

Langkah 5: Buat Ulang Key Bila Perlu

Jika sebuah key diduga bocor, klik Regenerate Key dan segera perbarui penerima webhook Anda.

Setelah dibuat ulang, signature lama harus dianggap tidak valid.

Catatan validasi:

• Rotasi key di penerima Anda lebih dulu (atau dengan peluncuran secret tanpa downtime) untuk meminimalkan pengiriman yang gagal.
• Picu event uji setelah rotasi dan pastikan hanya secret baru yang berhasil divalidasi.
• Request apa pun yang ditandatangani dengan secret lama sekarang harus gagal dalam verifikasi signature.

Langkah 6: Simpan Setelan Escalation

Klik Save di halaman Escalation setelah mengubah webhook.

Tidak ada pengiriman webhook sampai perubahan disimpan dan event escalation terjadi.

Penyimpanan membuat agent Anda masuk ke draft. Escalation dari agent live baru memakai setelan webhook setelah Anda mengklik Publish (lihat Preview dan Publish Perubahan).

Catatan validasi:

• Tunggu pesan simpan berhasil sebelum meninggalkan halaman.
• Buka kembali setelan Escalation dan pastikan Webhook tetap aktif dengan URL yang diharapkan.
• Jika setelan kembali seperti semula, periksa error validasi atau editan yang bertabrakan dari sesi lain.

Langkah 7: Pahami Tipe Event Escalation

Notifikasi webhook dikirim untuk event siklus hidup berikut:

Catatan validasi:

• Pastikan penerima Anda mengarahkan logika berdasarkan eventType dan menangani keempat event dengan baik.
• Tangani nilai event baru yang belum dikenal di masa depan dengan aman (misalnya catat di log lalu lewati), alih-alih membuat seluruh endpoint gagal.

Langkah 8: Contoh Payload

Endpoint Anda harus menerima payload JSON dengan bentuk serupa ini:

{
  "eventType": "created",
  "timestamp": "2026-05-19T10:15:00Z",
  "agentId": "agent-123",
  "escalation": {
    "id": "esc-001",
    "threadId": "thread-abc",
    "status": "Pending",
    "urgencyLevel": "high",
    "topic": "refund",
    "area": "payment",
    "reason": "User is angry and demands immediate refund",
    "triggerCondition": "Angry Customer Escalation"
  }
}

Field payload yang persis bisa berubah, jadi rancang penerima agar mengabaikan field yang tidak dikenal dengan aman.

Catatan validasi:

• Validasi field yang wajib untuk alur kerja Anda (misalnya eventType, timestamp, dan pengenal escalation) dan abaikan field tambahan yang opsional.
• Buat parser Anda toleran terhadap penambahan schema agar tidak rusak saat ada field baru.

Langkah 9: Verifikasi Signature Request (Disarankan)

Validasi request yang masuk dengan HMAC-SHA256 menggunakan secret key webhook Anda.

Alur verifikasi yang disarankan:

1. Baca byte mentah body request.
2. Hitung HMAC-SHA256 menggunakan secret yang tersimpan.
3. Bandingkan dengan header signature menggunakan perbandingan constant-time.
4. Tolak signature yang tidak cocok dengan 401 atau 403.

Catatan validasi:

• Selalu verifikasi terhadap byte mentah body, bukan objek JSON yang diserialisasi ulang.
• Tolak request yang tidak punya header signature.
• Catat kegagalan verifikasi di log tanpa mencatat body request yang sensitif atau nilai secret.

Periksa hasilnya: Kirim Event Uji Sungguhan

Jalankan alur uji sederhana ini:

1. Picu satu escalation user yang marah.
2. Lakukan claim dari workspace supervisor.
3. Selesaikan dengan catatan penyelesaian.

Anda seharusnya melihat event created, claimed, dan completed sampai ke penerima webhook Anda.

Catatan validasi:

• Pastikan urutan kedatangan dan timestamp di log penerima Anda.
• Pastikan setiap event diproses secara idempoten agar retry tidak menimbulkan efek samping ganda.
• Simpan jejak request/response untuk sementara waktu agar troubleshooting selama peluncuran lebih mudah.

Langkah berikutnya

• Berikutnya dalam jalur ini: Anda sudah menyelesaikan Tahap 2. Mulai Tahap 3 dengan Mencari dan Membaca Web, agar agent Anda bisa mencari informasi di luar knowledge-nya.
• Tinjau seluruh alur escalation: Mengalihkan ke Manusia.
• Menerima dan Mengelola Escalation: workspace supervisor.