Mengirim Event Escalation ke Webhook
Buka di CMSWebhook memungkinkan qlar memberi tahu sistem Anda hampir secara real-time saat event escalation terjadi, misalnya untuk:
- Membuat atau memperbarui tiket di tool helpdesk Anda
- Mengirim notifikasi ke channel Slack atau Teams
- Memicu alur kerja monitoring atau kepatuhan internal
Pada contoh ini, Kirana Group mengirim event escalation Atlas ke endpoint internalnya https://hooks.kirana.example/qlar/escalations, yang meneruskan setiap kasus baru ke channel operations duty.
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 dijangkau dari internet, yang bisa menerima request uji dan menampilkan body-nya.
Langkah 1: Buka bagian Webhook notifications
Di CMS, buka Conversation โ Escalation lalu gulir ke Webhook notifications. Bagian ini berada di halaman yang sama dengan setelan escalation lainnya dan disimpan dengan tombol Save yang sama.
Langkah 2: Aktifkan webhook
Nyalakan Send webhook notifications. Petunjuknya berbunyi: "Get an HTTP POST when an escalation is created, claimed, completed or released." Baris Webhook URL dan Secret key muncul.
Langkah 3: Atur webhook URL
Masukkan endpoint Anda di Webhook URL. Field ini wajib diisi selama webhook aktif dan harus diawali https://, seperti petunjuk di bawah field. Jika field kosong atau URL tidak diawali https://, field menampilkan Enter a webhook URL. atau Start the URL with https://. Untuk Kirana:
https://hooks.kirana.example/qlar/escalations
Pakai endpoint yang bisa dijangkau dari internet (bukan localhost), dan periksa log server atau API gateway Anda untuk memastikan request ke path ini diterima.

Kotak Secret key masih bertuliskan Not generated yet. Save to create a key. Key dibuat saat Anda menyimpan.
Langkah 4: Simpan, lalu salin secret key
- Klik Save di bagian bawah halaman Escalation. Dialog Saved mengonfirmasi Escalation settings saved.
- Kotak Secret key sekarang berisi key yang sudah dibuat. Klik tombol copy di ujung kanannya (tooltip-nya berbunyi Copy key, lalu Copied) dan simpan key itu di penyimpanan secret backend Anda (misalnya environment secret atau vault), bukan di source control.
Petunjuknya menjelaskan fungsi key-nya: "Check this key in your webhook handler to confirm a request comes from this platform."

Jangan taruh key di kode frontend atau log publik, dan samarkan di dashboard.
Penyimpanan membuat agent Anda berstatus draft. Escalation di Preview langsung memakai webhook; escalation dari agent live baru memakainya setelah Anda mengklik Publish (lihat Preview dan Publish Perubahan).
Langkah 5: Buat ulang key bila perlu
Jika key mungkin bocor, klik Regenerate key. CMS mengonfirmasi A new webhook secret key has been generated. Salin key baru, perbarui receiver Anda, lalu simpan dan publish agar agent live juga memakainya. Request dengan key lama sekarang harus ditolak oleh receiver Anda.
Langkah 6: Baca dokumentasi API
Di baris API docs di bagian bawah, klik Show API docs. Dokumentasinya terbuka tepat di bawahnya, di halaman yang sama, dengan tiga tab:
- Overview: cara pengiriman bekerja dan tipe event.
- Payload: secret key, contoh payload, dan referensi field.
- Code examples: receiver kecil dalam Node.js, C#, Python, dan Java. Pilih bahasa lewat tab di header blok kode, dan pakai Copy untuk menyalin kodenya.
Tombolnya sekarang bertuliskan Hide API docs. Klik untuk menutup dokumentasi itu lagi.

Langkah 7: Pahami tipe event
Setiap request membawa satu event di eventType:
| Event | Kapan dikirim | Status sesudahnya |
|---|---|---|
escalation.created | AI memunculkan escalation baru | Pending |
escalation.updated | AI meng-escalate lagi thread yang sudah punya escalation terbuka | Pending |
escalation.claimed | Supervisor melakukan claim pada kasus | InProgress |
escalation.completed | Supervisor menyelesaikannya | Completed |
escalation.released | Owner atau Contributor agent mengembalikannya ke Pending | Pending |
Petunjuk Send webhook notifications menyebut empat event utama (created, claimed, completed, released). Dokumentasi API juga mencantumkan escalation.updated. Arahkan logika Anda berdasarkan eventType, tangani kelima event, dan catat lalu lewati nilai yang tidak Anda kenali alih-alih gagal.
Langkah 8: Periksa payload
Setiap event berupa POST JSON. Contoh ini menampilkan kasus Atlas dari tutorial sebelumnya:
{
"secret": "your-webhook-secret-key",
"eventType": "escalation.created",
"timestamp": "2026-10-04T18:29:00.000Z",
"data": {
"escalationId": "b75f06a1-...",
"agentId": "YOUR_AGENT_ID",
"agentName": "Atlas",
"threadId": "thread-...",
"status": "Pending",
"topic": "Approval limits",
"area": "Kirana Group",
"triggerCondition": "Decision outside the SOPs",
"urgencyLevel": "high",
"reason": "User requests an exception to approve a USD 1.2 million project themselves because the Regional Director is on leave and vendor deadline is tomorrow.",
"endUser": {
"userId": "...",
"displayName": "Rina Wijaya",
"email": "rina.wijaya@kirana.example",
"phoneNumber": "6281200000000"
},
"supervisor": null,
"resolutionNote": null,
"createdAt": "2026-10-04T18:29:00.000Z",
"updatedAt": "2026-10-04T18:29:00.000Z",
"completedAt": null
}
}
supervisorterisi setelah seseorang melakukan claim pada kasus, sedangkanresolutionNotedancompletedAtterisi padaescalation.completed.urgencyLevelbernilailow,medium,high, ataucritical.- Tab Payload berisi referensi field lengkap. Field bisa bertambah seiring waktu, jadi abaikan field yang tidak Anda pakai.
Langkah 9: Verifikasi secret
Setiap body request membawa field secret. Bandingkan dengan key yang Anda simpan di Langkah 4 dan tolak request dengan 401 jika tidak cocok. Tab Code examples menampilkan pemeriksaan ini dalam setiap bahasa. qlar tidak menandatangani request lewat header, jadi field secret adalah pemeriksaan yang bisa diandalkan.
Beberapa aturan lagi untuk receiver yang andal:
- Jawab dengan cepat memakai status
2xx. qlar menunggu paling lama 10 detik untuk setiap request dan tidak mengulang, jadi kerjakan pekerjaan yang lambat (membuat tiket, mengirim pesan) setelah Anda merespons. - Proses event secara idempoten, memakai
data.escalationIddaneventType, agar duplikat tidak pernah membuat tiket kedua. - Jangan pernah mencatat nilai
secretdi log.
Periksa hasilnya: kirim event uji sungguhan
Jalankan alur uji ini:
- Di chat Preview, picu satu escalation, seperti di Mengatur Escalation.
- Di antrean Preview, lakukan claim dengan CLAIM TICKET.
- Tulis resolution note lalu klik COMPLETE.
Receiver Anda seharusnya menerima escalation.created, escalation.claimed, dan escalation.completed untuk escalationId yang sama, masing-masing dengan secret yang benar.
Jika tidak ada yang masuk, periksa bahwa Send webhook notifications menyala, Anda sudah menyimpan setelah mengubahnya, URL diawali https:// dan bisa dijangkau dari internet, dan, untuk agent live, Anda sudah publish.
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.