Mengirim Event Escalation ke Webhook

Buka di CMS

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

Bagian Webhook notifications dengan Send webhook notifications menyala, Webhook URL https://hooks.kirana.example/qlar/escalations dengan petunjuk Must start with https://, Secret key (diburamkan) dengan tombol salin dan tombol Regenerate key, dan baris API docs dengan Show API docs

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

  1. Klik Save di bagian bawah halaman Escalation. Dialog Saved mengonfirmasi Escalation settings saved.
  2. 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."

Baris Secret key dengan kunci yang dihasilkan (diburamkan di sini) dan tombol salin, di atas tombol Regenerate key

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.

Bagian Webhook notifications dengan baris API docs terbuka di tab Overview (tab Overview, Payload dan Code examples): platform mengirim HTTP POST ke endpoint Anda, dan tabel Event types mencantumkan escalation.created, escalation.updated, escalation.claimed, escalation.completed dan escalation.released beserta pemicu dan statusnya

Langkah 7: Pahami tipe event

Setiap request membawa satu event di eventType:

EventKapan dikirimStatus sesudahnya
escalation.createdAI memunculkan escalation baruPending
escalation.updatedAI meng-escalate lagi thread yang sudah punya escalation terbukaPending
escalation.claimedSupervisor melakukan claim pada kasusInProgress
escalation.completedSupervisor menyelesaikannyaCompleted
escalation.releasedOwner atau Contributor agent mengembalikannya ke PendingPending

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
  }
}
  • supervisor terisi setelah seseorang melakukan claim pada kasus, sedangkan resolutionNote dan completedAt terisi pada escalation.completed.
  • urgencyLevel bernilai low, medium, high, atau critical.
  • 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.escalationId dan eventType, agar duplikat tidak pernah membuat tiket kedua.
  • Jangan pernah mencatat nilai secret di log.

Periksa hasilnya: kirim event uji sungguhan

Jalankan alur uji ini:

  1. Di chat Preview, picu satu escalation, seperti di Mengatur Escalation.
  2. Di antrean Preview, lakukan claim dengan CLAIM TICKET.
  3. 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