Webhook

Pengaturan Webhook

Copy page

Pengaturan webhook terdiri dari dua bagian: menambahkan webhook ke sebuah channel di dashboard Chatmo, dan menyiapkan endpoint di server Anda sendiri yang menerima event-nya. Halaman ini membahas keduanya.

Membuat webhook di Chatmo

Bagian ini membahas cara menambahkan webhook dari dashboard. Untuk apa yang perlu diimplementasikan di server Anda sendiri untuk menerimanya, lihat Menyiapkan endpoint Anda di bawah.

1. Buka modul Webhook

Buka Integrations di sidebar, lalu buka kartu Webhook.

• Jika ini webhook pertama Anda, kartu akan menampilkan Connect.
• Jika Anda sudah memiliki satu atau lebih webhook, kartu akan menampilkan Manage Integration.

Keduanya mengarah ke tempat yang sama — daftar webhook untuk organisasi Anda.

2. Klik Add Webhook

Pada halaman Webhook, klik Add Webhook. Sebuah form akan terbuka dengan field berikut:

Field	Deskripsi
Channel	Channel yang akan didengarkan webhook ini. Cari berdasarkan nama — semua channel yang terhubung (WhatsApp Official, WhatsApp Unofficial, Instagram, Facebook Messenger, Telegram, atau Webchat) dapat dipilih.
Webhook Name	Label internal agar Anda bisa membedakan webhook satu dengan lainnya — tidak pernah dikirim ke endpoint Anda.
Webhook URL	URL https:// yang akan menerima POST event dari Chatmo.
Advanced: Custom Headers	Pasangan key/value opsional yang dikirim di setiap request, misalnya header Authorization milik Anda sendiri. Lihat Autentikasi & Keamanan.
Event Types	Event mana saja yang diterima webhook ini. Dikelompokkan per kategori, dengan event yang tidak didukung channel yang Anda pilih ditampilkan abu-abu (tidak bisa dipilih).
Include raw provider payload	Nonaktif secara default. Menambahkan field raw_payload ke setiap pengiriman, berisi payload yang diterima Chatmo dari channel — paling berguna untuk mengakses file asli dari pesan media. Lihat Contoh Payload.

:::tip Memilih jenis event Pilih hanya event yang benar-benar akan Anda proses. Semakin sedikit langganan, semakin sedikit pengiriman yang perlu diproses — dan jika channel Anda tidak mendukung suatu event (misalnya, Telegram tidak memiliki webhook status pengiriman), event tersebut dinonaktifkan di daftar agar tidak salah pilih. :::

3. Simpan dan salin signing secret

Saat Anda klik Create Webhook, Chatmo membuat signing secret unik untuk endpoint ini dan menampilkannya kepada Anda satu kali. Salin sekarang — Anda akan membutuhkannya untuk memverifikasi request yang masuk (lihat Autentikasi & Keamanan), dan secret ini tidak akan ditampilkan secara lengkap lagi setelahnya.

Jika Anda kehilangannya, buka panel Edit webhook tersebut dan klik Regenerate untuk membuat secret baru. Regenerate langsung membatalkan secret yang lama.

4. Verifikasi webhook berfungsi

Gunakan tombol Test (ikon tabung reaksi) pada baris webhook untuk mengirim payload contoh untuk salah satu event yang dilanggan saat ini juga, tanpa perlu menunggu event sungguhan terjadi. Lihat Pengujian & Log Pengiriman.

Mengelola webhook yang sudah ada

Dari daftar webhook, Anda dapat:

• Edit — mengubah nama, URL, custom header, atau langganan event.
• Test — mengirim satu event contoh.
• View Logs — melihat setiap percobaan pengiriman, dapat difilter berdasarkan status, kode HTTP, jenis event, dan rentang tanggal.
• Activate / Deactivate — menjeda pengiriman tanpa menghapus konfigurasi.
• Delete — menghapus webhook secara permanen.

:::warning Nonaktif otomatis setelah kegagalan berulang Jika sebuah webhook gagal 20 kali pengiriman berturut-turut, Chatmo secara otomatis menonaktifkannya dan mengirim email ke pemilik organisasi — ini mencegah endpoint yang mati dicoba ulang selamanya. Perbaiki endpoint Anda, lalu ubah kembali statusnya menjadi Active dari panel Edit. :::

Menyiapkan endpoint Anda

Webhook endpoint hanyalah sebuah route HTTP di server Anda sendiri yang menerima request POST. Bagian ini membahas apa yang perlu dilakukan agar dapat menerima event Chatmo dengan benar.

Persyaratan minimum

Endpoint Anda harus:

1. Menerima request POST melalui HTTPS. HTTP biasa secara teknis tetap diterima namun sangat tidak disarankan — payload dapat berisi konten pesan dan detail kontak.
2. Membaca raw request body sebelum memverifikasi signature (lihat Autentikasi & Keamanan) — beberapa framework mem-parsing JSON sebelum handler Anda berjalan, yang dapat mengubah byte persis yang digunakan untuk menghitung signature.
3. Merespons dengan cepat. Chatmo menunggu hingga 10 detik untuk sebuah response sebelum menganggap percobaan tersebut gagal dan menjadwalkan retry. Jangan lakukan pekerjaan yang lambat (memanggil API lain, pemrosesan berat) di dalam request handler — konfirmasi dulu, proses setelahnya.
4. Mengembalikan status 2xx saat berhasil. Status lainnya — atau tidak ada response dalam batas waktu — dianggap sebagai pengiriman gagal dan akan di-retry.

:::tip Konfirmasi dulu, baru proses Kesalahan webhook yang paling umum adalah melakukan semua pekerjaan secara sinkron di dalam handler. Sebagai gantinya, verifikasi signature, masukkan payload ke queue atau background job, lalu langsung kembalikan 200. Lakukan pemrosesan sebenarnya (menulis ke database, memanggil sistem lain) di luar siklus request/response. :::

Contoh endpoint minimal

Code
// Node.js / Express — raw body dibutuhkan untuk verifikasi signature
app.post(
  '/webhooks/chatmo',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const signature = req.header('X-Chatmo-Signature');
    if (!isValidSignature(req.body, signature)) {
      return res.status(401).send('invalid signature');
    }

    const event = JSON.parse(req.body);
    // Konfirmasi langsung — lakukan pekerjaan sebenarnya secara asynchronous.
    res.status(200).send('ok');

    processEventAsync(event);
  }
);

Lihat Contoh Kode untuk verifikasi signature dalam cURL, Node.js, Python, PHP, dan Go.

Menangani response non-retryable dengan benar

Chatmo memperlakukan 401, 403, dan 410 sebagai non-retryable — artinya Chatmo menganggap autentikasi endpoint Anda salah atau URL memang sengaja sudah tidak ada, sehingga langsung berhenti mencoba ulang pengiriman tersebut alih-alih menghabiskan seluruh jatah retry. Gunakan status tersebut hanya untuk kondisi itu:

Anda mengembalikan	Yang dilakukan Chatmo
2xx	Menandai pengiriman berhasil.
401 / 403	Langsung menandai pengiriman gagal — tidak di-retry. Gunakan hanya saat signature benar-benar tidak cocok.
410	Langsung menandai pengiriman gagal — tidak di-retry. Gunakan jika endpoint sudah permanen tidak aktif (Chatmo tidak akan berhenti mengirim dengan sendirinya; nonaktifkan webhook dari dashboard sebagai gantinya).
Lainnya (5xx, 429, timeout, connection error)	Di-retry dengan backoff — lihat Percobaan Ulang & Jaminan Pengiriman.

Jika endpoint Anda hanya sementara tidak dapat memproses request (deployment sedang berjalan, dependensi lain sedang down), kembalikan 5xx — ini memberi tahu Chatmo untuk mencoba ulang, yang memang Anda inginkan.

Idempotency

Setiap pengiriman membawa header X-Chatmo-Delivery-Id yang unik. Jika endpoint Anda menerima delivery ID yang sama dua kali (misalnya retry yang sebenarnya berhasil di sisi Anda tapi response-nya hilang di tengah jalan), perlakukan yang kedua sebagai no-op. Simpan delivery ID yang sudah diproses selama jangka waktu yang wajar dan periksa sebelum memproses event yang sama untuk kedua kalinya.

Checklist sebelum go-live

• Endpoint dapat diakses melalui HTTPS dari internet publik
• Verifikasi signature menggunakan raw request body, bukan objek JSON yang di-serialize ulang
• Handler merespons dalam beberapa detik, pekerjaan sebenarnya dilakukan secara asynchronous
• 401/403/410 hanya dikembalikan saat memang sesuai
• Delivery ID di-deduplikasi di sisi Anda
• Anda sudah mengirim test event untuk setiap jenis event yang dilanggan dan memastikan diterima dengan benar