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
• 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 kartu Webhook Notifications

Di CMS, buka Conversation → Escalation lalu gulir ke Webhook Notifications. Kartu ini berada di halaman yang sama dengan setelan escalation lainnya dan disimpan dengan tombol Save yang sama.

Langkah 2: Aktifkan webhook

Nyalakan switch-nya. Labelnya berubah menjadi Enabled: "Receive HTTP POST notifications when escalation events occur (created, claimed, completed, released)." Field 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. 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 yet generated — save first). Key dibuat saat Anda menyimpan.

Langkah 4: Simpan, lalu salin secret key

1. Klik Save di bagian bawah halaman Escalation. Sebuah pesan mengonfirmasi Escalation settings saved successfully.
2. Kotak Secret Key sekarang berisi key yang sudah dibuat. Klik tombol copy di ujung kanannya dan simpan key itu di penyimpanan secret backend Anda (misalnya environment secret atau vault), bukan di source control.

Kartu ini menjelaskan fungsi key-nya: "Include this key in your webhook handler to verify requests originate 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

Klik Show API Documentation di bawah kartu. Panel Webhook API Documentation punya 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.

Hide API Documentation menutup panel itu lagi.

Langkah 7: Pahami tipe event

Setiap request membawa satu event di eventType:

Deskripsi kartu 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 webhook dalam keadaan Enabled, 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.