Langsung ke konten
ID EN

Webhook

6 min read

Setiap bagian adalah tugas bernomor — ikuti langkahnya, periksa Anda seharusnya melihat, lalu lanjutkan. Untuk referensi layar lengkap, lihat Referensi webhook.

Tambahkan endpoint webhook

Tujuan: Daftarkan URL HTTPS yang menerima event JSON Kirisan.

Mulai saat: Endpoint server Anda siap menerima permintaan POST dan mengembalikan 200 atau 201.

  1. Buka Webhooks → Webhook dan klik Add webhook.

    • Anda seharusnya melihat modal New webhook dengan bagian Endpoint, Devices, Events, dan Security.

New webhook modal

  1. Di bawah Endpoint, masukkan Display name dan HTTPS URL Anda (misalnya https://api.yoursite.com/webhooks/kirisan).

  2. Di bawah Devices, pilih tab channel (WhatsApp, Telegram, atau WABA) dan pilih setidaknya satu device.

  3. Di bawah Events, centang setidaknya satu: Incoming Message atau Submission (WABA juga punya Message status).

  4. Opsional: atur Signing secret — Kirisan mengirimkannya sebagai X-Webhook-Secret di setiap POST.

  5. Klik Save → test.

    • Anda seharusnya melihat Webhooks → Test terbuka untuk endpoint baru. Status menampilkan Pending test di Webhooks → Webhook sampai tes berhasil.

Selesai saat: Endpoint muncul di tabel dengan URL dan event Anda.

Aktifkan dengan tes (Pending test → Active)

Tujuan: Pindahkan endpoint dari Pending test ke Active dengan mengembalikan 2xx.

Mulai saat: Anda mendarat di Webhooks → Test setelah menyimpan (atau endpoint menampilkan Pending test).

  1. Buka Webhooks → Test dan pilih endpoint Anda di dropdown Webhook.

    • Label menampilkan name · device · event · URL. Endpoint yang belum diverifikasi menyertakan pending di label.

Webhook test form

  1. Tinjau Payload preview — konfirmasi bentuk JSON cocok dengan yang diharapkan handler Anda.

  2. Klik Send test.

    • Anda seharusnya melihat kartu hasil: Success atau Failed, status HTTP, durasi, dan body respons.

Successful webhook test

  1. Pada Success, buka Webhooks → Webhook dan konfirmasi endpoint menampilkan Active.

Selesai saat: Status Active di Webhooks → Webhook.

Satu tes berhasil mengaktifkan setiap endpoint dari batch Save → test yang sama. Anda tidak perlu menguji setiap endpoint secara terpisah.

Uji webhook submission

Tujuan: Verifikasi payload event Submission sebelum formulir asli selesai.

Mulai saat: Anda mengaktifkan Submission pada endpoint dan menghubungkan device yang memiliki formulir autoreply.

  1. Di Webhooks → Test, pilih baris yang labelnya menyertakan submission.
  2. Konfirmasi Payload preview menyertakan submission, answers, dan "production": false.
  3. Klik Send test dan konfirmasi Success.
  4. Opsional: selesaikan submission uji nyata pada device terhubung dan bandingkan hasil di Webhooks → Logs.

Selesai saat: Handler Anda mem-parsing array answers sampel tanpa error.

Tambahkan device ke endpoint yang ada

Tujuan: Kirim event dari device baru ke URL yang sudah Anda punya.

  1. Di Webhooks → Webhook, klik Edit pada baris endpoint.
  2. Ganti tab channel dan pilih device tambahan.
  3. Klik Save → test dan jalankan tes berhasil jika status reset ke Pending test.
  4. Konfirmasi jumlah Devices pada baris terbarui.

Selesai saat: Lalu lintas live sampai untuk setiap device terhubung.

Periksa pengiriman yang gagal

Tujuan: Pahami mengapa Kirisan tidak bisa mengirim webhook dan apa yang diperbaiki di server Anda.

  1. Buka Webhooks → Logs dan setel All statuses ke Failed.

    • Anda seharusnya melihat hanya baris di mana server mengembalikan kode non-2xx, habis waktu, atau tidak bisa dijangkau.

Webhook logs — filter by failed status

  1. Opsional: filter All devices untuk menyempit ke satu jalur atau bot.

  2. Klik baris yang gagal.

    • Anda seharusnya melihat Webhook delivery dengan HTTP code, Duration, Device, dan panel Error.

Failed delivery detail

  1. Baca Error dan HTTP code:

    • 503 / 502 — server menolak atau kelebihan beban
    • 401 / 403 — periksa X-Webhook-Secret jika Anda mengatur signing secret
    • 0 atau timeout — Kirisan tidak bisa terhubung; verifikasi DNS, TLS, dan firewall

  2. Perbaiki handler Anda, kirim tes baru dari Webhooks → Test, lalu konfirmasi baris success di Webhooks → Logs.

Selesai saat: Upaya terbaru menampilkan success.

Debug pengiriman untuk satu device

  1. Buka Webhooks → Logs.
  2. Di All devices, pilih device (label menampilkan nama + nomor atau nama bot).
  3. Pindai kolom Webhook dan URL untuk konfirmasi endpoint yang benar aktif.
  4. Klik baris mana pun untuk detail device dan waktu lengkap.

Perbaiki masalah umum

Gejala: Belum ada webhook — halaman kosong.

  • Anda belum menyimpan endpoint — klik Add webhook.
  • Anda mungkin di akun yang salah — periksa email di bilah atas.

Gejala: Status tetap Pending test.

  • Buka Webhooks → Test dan kirim tes — URL Anda harus mengembalikan 200 atau 201.
  • Konfirmasi URL HTTPS dan bisa dijangkau dari internet publik.
  • Periksa Webhooks → Logs untuk error TLS atau timeout.

Gejala: Tes berhasil tetapi pesan live tidak pernah sampai.

  • Konfirmasi status endpoint Active (bukan Pending test) di Webhooks → Webhook.
  • Untuk Incoming Message: buka dialog edit device dan setel On incoming message → Webhook. Device harus menggunakan Webhook sebagai handler masuk atau tidak ada event yang aktif.
  • Lalu lintas live menggunakan "production": true — konfirmasi handler Anda tidak menolak payload production.

Gejala: Incoming Message tidak pernah aktif pada lalu lintas live.

  • Konfirmasi On incoming message → Webhook disetel pada device (bukan Autoreply, Flow, atau Spreadsheet).
  • Konfirmasi device terhubung pada endpoint dan endpoint Active.
  • Hanya event yang dicentang yang aktif — aktifkan Incoming Message di editor endpoint.

Gejala: Event submission tidak pernah aktif.

  • Aktifkan Submission pada endpoint dan hubungkan device yang memiliki formulir autoreply.

Gejala: Tes mengembalikan 401 atau 403.

  • Saat Anda mengatur signing secret, handler harus membaca X-Webhook-Secret dari header permintaan.
  • Izinkan payload tes dengan "production": false jika handler Anda memfilter field itu.

Gejala: Tes mengembalikan timeout atau error koneksi.

  • Konfirmasi URL HTTPS dan bisa dijangkau dari internet publik (bukan localhost atau IP privat).
  • Periksa validitas sertifikat TLS.
  • Tinjau Webhooks → Logs untuk teks error yang sama.

Gejala: Daftar log kosong meskipun endpoint aktif.

  • Reset semua filter (All events, All statuses, All channels, All devices).
  • Untuk event Incoming Message, konfirmasi device menggunakan On incoming message → Webhook di pengaturan device.
  • Picu pesan nyata atau gunakan Webhooks → Test, lalu refresh Webhooks → Logs.

Gejala: Server menolak permintaan.

  • Parse JSON dari body permintaan. Gunakan header X-Kirisan-Event dan X-Kirisan-Device untuk routing.
  • Saat signing secret disetel, bandingkan X-Webhook-Secret dengan nilai yang Anda konfigurasi sebelum memproses.

Terkait

Was this page helpful?