Lewati ke isi
CSWA.AIDocs

API & Webhook: mengatur webhook

Tambah URL webhook, pilih event, verifikasi tanda tangan, uji kirim, dan baca log kiriman.

± 5 menit

Webhook mengirim kejadian (pesan masuk, status, pesanan, dll.) ke URL server Anda secara langsung, ditandatangani agar bisa diverifikasi.

Sebelum mulai

  • Izin peran: Integrasi › Kelola (pemilik & admin otomatis punya).
  • URL https publik di server Anda yang menjawab 2xx dalam 10 detik.
  • Maks. 5 URL webhook per Profil.

Langkah#

  1. Langkah 1: Tambah URL

    Di API & Webhook › tab Webhook, klik Tambah URL. Isi URL https, mis. https://kopisenja.com/webhook.

    ① Tab Webhook. ② Form URL webhook baru. ③ Pilihan event.

    API & Webhook tab Webhook: tombol Tambah URL dan pilihan event

  2. Langkah 2: Pilih event

    Centang event yang diperlukan (daftar di bawah), lalu klik Tambah URL.

  3. Langkah 3: Simpan rahasia & verifikasi

    Kartu Rahasia webhook — simpan di server Anda muncul berisi rahasia dan contoh kode verifikasi (Node.js, PHP, Python). Header X-CSWA-Signature berisi t=<detik>,v1=<HMAC-SHA256(rahasia, t + "." + badan)>. Tolak bila tidak cocok atau lebih dari 5 menit.

  4. Langkah 4: Uji kirim

    Klik Uji kirim. Berhasil: “Server Anda menjawab HTTP 200 dalam … ms”. Gagal: periksa URL & log server.

  5. Langkah 5: Pantau log

    Tab Log, pilih Kiriman webhook untuk melihat event, status, percobaan, HTTP, dan galat. Kiriman gagal bisa dikirim ulang. Log disimpan 14 hari.

Hasilnya#

URL tampil di daftar dengan status Sehat dan event yang dipilih. Setiap kiriman membawa header X-CSWA-Event, X-CSWA-Delivery, dan X-CSWA-Timestamp.

Terhubung dengan fitur lain#

  • Kiriman gagal diulang otomatis setelah 1 menit, 5 menit, 30 menit, 2 jam, 6 jam, 12 jam.
  • URL yang gagal terus selama 3 hari dinonaktifkan otomatis dan pemiliknya diberi tahu. Nyalakan lagi dengan Nyalakan.
  • Rotasi rahasia: rahasia lama tetap ikut ditandatangani 24 jam — ganti rahasia di server Anda dalam waktu itu.
  • Contoh penerima lengkap — Panduan webhook.

Daftar event#

message.receivedPesan masuk dari pelanggan (semua jenis, dengan tautan media sementara).
message.statusStatus pesan keluar berubah: terkirim, diterima, dibaca, atau gagal.
message.sentPesan keluar dari mana pun: CS, AI Agent, automasi, broadcast, atau API.
conversation.assignedPercakapan ditugaskan ke anggota tim atau dilepas.
conversation.closedPercakapan ditandai selesai.
ai.handoverAI Agent menyerahkan percakapan ke CS manusia.
channel.connectedNomor WhatsApp tersambung.
channel.disconnectedNomor WhatsApp terputus.
broadcast.finishedBroadcast selesai, dihentikan, atau gagal — dengan ringkasan angka.
contact.createdKontak WhatsApp baru tersimpan (chat masuk, impor, Inbox, atau API).
contact.taggedTag baru ditambahkan ke kontak WhatsApp (berisi tag yang ditambahkan).
order.createdPesanan baru dibuat (Inbox, AI Agent, tagihan, atau checkout halaman toko).
order.paidPesanan lunas (Mayar, transfer dikonfirmasi, atau mutasi terdeteksi otomatis).
order.shippedPesanan dikirim — kurir & resi diisi.
ticket.createdTiket baru dibuat oleh tim atau AI Agent.
csat.submittedPelanggan memberi nilai survei kepuasan (CSAT).

Event contact.created, contact.tagged, order.created, order.paid, order.shipped, ticket.created, csat.submitted hanya dikirim bila fiturnya termasuk paket Profil.

Masalah umum#

Status “Gagal”
Server tidak menjawab 2xx dalam 10 detik. Baca kolom galat di tab Log, perbaiki server, lalu kirim ulang.
Tanda tangan tidak cocok
Hitung HMAC dari badan mentah (bukan JSON yang sudah diurai ulang) dan pakai rahasia terbaru setelah rotasi.
Tombol Tambah URL hilang
Batas 5 URL per Profil tercapai. Hapus atau gabungkan URL.
Event yang sama datang dua kali
Kiriman bisa diulang. Pakai header X-CSWA-Delivery untuk mengabaikan duplikat.

Terkait#