Echobell
App Store Google Play

Integrasi Webhook - Panduan Lengkap Pemicu HTTP

Integrasikan webhook Echobell: metode HTTP, variabel, templat, header, dan contoh nyata untuk peringatan instan di ponsel.

Webhook adalah cara paling serbaguna untuk memicu notifikasi Echobell. Panduan menyeluruh ini membahas semua yang perlu Anda ketahui tentang mengintegrasikan peringatan berbasis webhook ke sistem Anda, mulai dari konsep dasar sampai pola penggunaan tingkat lanjut.

Apa itu webhook

Webhook adalah cara sebuah aplikasi menyediakan informasi real-time ke aplikasi lain lewat callback HTTP. Bayangkan seperti nomor telepon yang Anda berikan ke seseorang - saat mereka menelepon nomor itu, ponsel Anda berdering. Di dunia digital, saat sesuatu terjadi di satu sistem (seperti penggunaan CPU yang tinggi, build yang gagal, atau pesanan baru), sistem itu mengirim permintaan HTTP ke sebuah URL (webhook) yang Anda berikan, sehingga memicu tindakan di sistem Anda.

Misalnya, saat penggunaan CPU server Anda terlalu tinggi, sistem pemantauan Anda bisa memanggil URL webhook Echobell, yang kemudian memicu notifikasi untuk memberi tahu Anda. Ini terjadi otomatis dan real-time, tanpa Anda harus terus-menerus memeriksa penggunaan CPU sendiri.

Webhook adalah fondasi arsitektur berbasis peristiwa dan didukung oleh hampir semua layanan cloud, alat pemantauan, dan platform SaaS modern. Webhook ringan, cepat, dan tidak butuh infrastruktur khusus di sisi Anda - cukup sebuah klien HTTP.

Manfaat Webhook

  • Real-time: Peristiwa memicu notifikasi secara instan, biasanya dalam 1-2 detik
  • Universal: Didukung hampir semua layanan dan bahasa pemrograman modern
  • Fleksibel: Kirim data khusus untuk membuat notifikasi yang kaya dan kontekstual
  • Andal: Berbasis HTTP, dengan kode status dan penanganan kesalahan yang standar
  • Skalabel: Tanpa polling - notifikasi dikirim hanya saat peristiwanya terjadi

Ringkasan

Setiap saluran Echobell bisa dikonfigurasi dengan URL webhook yang unik. Saat URL ini dipanggil, saluran tersebut mengirim notifikasi ke semua pelanggannya berdasarkan templat notifikasi yang dikonfigurasi dan variabel yang disediakan.

Format URL Webhook

https://hook.echobell.one/t/{channel-token}

Anda bisa menemukan URL webhook saluran Anda di tampilan detail saluran pada aplikasi Echobell.

Mengirim Permintaan Webhook

Webhook Echobell mendukung metode GET maupun POST:

Permintaan GET

Anda bisa mengirim variabel lewat parameter query:

GET https://hook.echobell.one/t/<channel-token>?server_name=Production&cpu_usage=95

Permintaan POST

Untuk permintaan POST, kirim variabel di dalam body JSON:

POST https://hook.echobell.one/t/<channel-token>
Content-Type: application/json

{
  "server_name": "Production",
  "cpu_usage": 95
}

POST Only

Setiap saluran punya sakelar POST Only di bawah Advanced Settings dalam aplikasi Echobell. Secara bawaan sakelar ini mati.

Saat sakelar itu menyala, hanya POST yang bisa memicu saluran tersebut. Permintaan GET ke URL webhook ditolak dengan 405 Method Not Allowed, dan tidak ada notifikasi yang dikirim:

{
  "success": false,
  "notificationTriggered": false,
  "message": "This trigger only accepts POST requests; GET triggering is disabled in its settings."
}

Permintaan HEAD tidak terpengaruh — permintaan itu dijawab 200 dan tidak pernah memicu notifikasi, baik POST Only menyala maupun mati.

Nyalakan sakelar ini kalau URL webhook Anda berakhir di tempat yang mengambil pratinjau tautan secara otomatis — pesan chat, halaman wiki, bilah alamat browser — supaya membuka atau mempratinjau URL itu tidak bisa menyalakan peringatan. Biarkan mati kalau ada pemanggil Anda yang memicu saluran dengan GET.

Variabel Khusus

Echobell mendukung sebuah variabel khusus yang menambahkan fungsi ke notifikasi Anda:

  • externalLink: Kalau disertakan dalam permintaan, variabel ini membuat tautan yang bisa diklik di tampilan riwayat notifikasi. Berguna untuk menautkan ke informasi rinci atau sumber terkait.

Contoh dengan external link:

POST https://hook.echobell.one/t/<channel-token>
Content-Type: application/json

{
  "server_name": "Production",
  "cpu_usage": 95,
  "externalLink": "https://dashboard.example.com/alerts/123"
}

Variabel Templat

Variabel yang dikirim lewat webhook bisa dipakai di templat notifikasi Anda dengan sintaks {{variableName}}:

Title: Server {{server_name}} Alert
Body: CPU usage has reached {{cpu_usage}}%

Saat terpicu, templat ini akan diisi dengan nilai yang Anda sediakan di permintaan webhook.

Variabel Waktu Sistem (UTC)

Selain data yang Anda kirim, Echobell menyediakan variabel waktu sistem yang bersifat baca‑saja dan selalu tersedia di templat maupun kondisi. Semua nilainya dihitung dalam UTC. Field datar mencakup date, time, year, month, dayOfWeek, hour, minute, dan second. Yang lain — seperti sys.dayOfWeekName, sys.epochMs, dan sys.epochSeconds — hanya tersedia di bawah namespace sys.. Lihat Kondisi untuk daftar lengkap dan contohnya.

Kasus Penggunaan Umum

Webhook adalah metode pemicu paling populer di Echobell dan sangat berguna untuk:

DevOps dan Pemantauan

  • Pemantauan Server: Peringatan penggunaan CPU, memori, dan disk dari sistem pemantauan seperti Prometheus atau Grafana
  • Pemantauan Uptime: Peringatan ketersediaan situs web dan layanan dari Uptime Kuma atau UptimeRobot
  • Pemantauan Kontainer: Kegagalan Docker, pod Kubernetes, dan keterbatasan sumber daya
  • Agregasi Log: Kesalahan dan exception kritis dari sistem manajemen log

Pengembangan dan CI/CD

  • Notifikasi Build: Build yang gagal, hasil pengujian, status deployment dari GitHub Actions atau GitLab CI
  • Kualitas Kode: Kesalahan lint, kerentanan keamanan, perubahan cakupan kode
  • Peristiwa Repositori: Pull request, commit, rilis, dan aktivitas kolaborator
  • Pelacakan Deployment: Deployment yang berhasil, rollback, dan perubahan environment

Aplikasi Bisnis

  • E-commerce: Pesanan baru, konfirmasi pembayaran, peringatan stok, pembaruan pengiriman
  • CRM: Prospek baru, kesepakatan yang tutup, tiket dukungan, interaksi pelanggan
  • Pemrosesan Pembayaran: Transaksi selesai, permintaan refund, peringatan penipuan
  • Pengiriman Formulir: Formulir kontak, jawaban survei, pendaftaran yang selesai

IoT dan Rumah Pintar

  • Peristiwa Rumah Pintar: Sensor pintu, deteksi gerakan, perubahan suhu lewat Home Assistant
  • Perangkat IoT: Pembacaan sensor, perubahan status perangkat, masalah konektivitas
  • Sistem Keamanan: Alarm yang berbunyi, deteksi gerakan kamera, peristiwa kontrol akses
  • Pemantauan Lingkungan: Suhu, kelembapan, dan kualitas udara yang melewati ambang batas

Trading dan Keuangan

  • Peringatan Pasar: Pergerakan harga, indikator teknikal dari TradingView
  • Pemantauan Portofolio: Perubahan posisi, margin call, saldo akun
  • Peristiwa Ekonomi: Rilis berita, laporan laba, perubahan sentimen pasar

Lihat panduan integrasi kami untuk petunjuk penyiapan spesifik pada platform-platform populer.

Praktik Terbaik

Penanganan Kesalahan

Jangan hanya mengandalkan status HTTP — selalu periksa body respons JSON dan cek field success:

  • 200 OK: Permintaan diterima. Periksa body JSON-nya: success: true berarti salurannya terpicu, sedangkan success: false berarti permintaannya diterima tetapi tidak ada notifikasi yang dikirim (misalnya, token saluran yang tidak dikenal, yang tetap mengembalikan HTTP 200).
  • 400 Bad Request: Panjang token saluran salah. Perbaiki URL webhook-nya.
  • 405 Method Not Allowed: Saluran itu mengaktifkan POST Only dan permintaannya bukan POST. Ubah pemanggilnya menjadi POST, atau matikan pengaturan tersebut.
  • 500 Server Error: Masalah sementara, coba lagi dengan exponential backoff

Echobell tidak membatasi frekuensi panggilan webhook, jadi tidak ada respons 429. Karena token yang tidak dikenal (tetapi panjangnya benar) tetap mengembalikan 200 dengan success: false, selalu ambil keputusan berdasarkan field success di JSON, bukan berdasarkan status HTTP.

Pembatasan Frekuensi

Terapkan jeda yang wajar antarpanggilan webhook agar sistem notifikasi Anda tidak kewalahan:

  • Untuk pemantauan berkelanjutan, gabungkan beberapa peristiwa jadi satu notifikasi
  • Gunakan kondisi untuk menyaring peristiwa yang tidak kritis
  • Pertimbangkan menggabungkan peristiwa yang datang beruntun (misalnya, banyak kesalahan dalam waktu singkat)
  • Hindari mengirim pemicu duplikat secara beruntun agar peringatan kritis tetap andal

Keamanan Data

Bagikan URL webhook hanya ke sistem dan layanan yang tepercaya:

  • Perlakukan URL webhook sebagai rahasia - URL itu memberi akses langsung untuk mengirim notifikasi
  • Jangan menaruh URL webhook di repositori publik atau membagikannya di dokumentasi publik
  • Ganti URL webhook secara berkala atau saat ada anggota tim yang keluar
  • Gunakan fitur "Reset Token" pada saluran untuk membatalkan URL lama kalau sampai bocor
  • Pertimbangkan memakai environment variable atau sistem manajemen rahasia untuk menyimpan URL

Penamaan Variabel

Gunakan nama variabel yang jelas dan konsisten di panggilan webhook Anda:

  • Pakai nama yang deskriptif: server_name, bukan s atau srv
  • Ikuti konvensi penamaan yang konsisten di semua saluran
  • Dokumentasikan variabel apa saja yang diharapkan templat Anda
  • Pastikan semua variabel yang diperlukan sudah ada sebelum mengirim

Pengujian

Uji integrasi webhook Anda secara menyeluruh sebelum dipakai di produksi:

  1. Gunakan alat seperti curl, Postman, atau klien HTTP bahasa Anda untuk pengujian awal
  2. Mulai dari templat sederhana lalu tambahkan kerumitannya secara bertahap
  3. Uji metode GET maupun POST untuk menemukan yang paling cocok
  4. Pastikan karakter khusus dan Unicode ditangani dengan benar
  5. Uji skenario kesalahan (variabel hilang, JSON rusak) untuk memahami perilakunya
  6. Pakai saluran uji coba yang terpisah dari saluran produksi selama pengembangan

Desain Templat

Rancang templat yang tetap berguna meski variabel opsionalnya tidak ada:

  • Sediakan nilai bawaan atau nilai cadangan untuk data opsional
  • Susun templat agar rapi menangani variabel yang hilang
  • Uji templat dengan berbagai kombinasi variabel yang ada dan tidak ada
  • Gunakan ekspresi kondisional untuk bagian yang opsional

Pemantauan

Pantau integrasi webhook Anda untuk memastikan semuanya bekerja dengan benar:

  • Catat panggilan webhook yang berhasil dan yang gagal di aplikasi Anda
  • Lacak tingkat pengiriman notifikasi dan waktu responsnya
  • Siapkan peringatan untuk kesalahan webhook atau pola yang tidak biasa
  • Tinjau dan uji integrasi webhook yang kritis secara berkala

Privasi dan Keamanan

Memahami cara Echobell menangani data webhook Anda:

Apa yang Disimpan

  • Di Server Kami:

    • URL webhook (token) - dibutuhkan untuk mengarahkan permintaan masuk ke saluran
    • Konfigurasi saluran - templat, kondisi, pengaturan
    • Relasi langganan - siapa berlangganan saluran yang mana

  • Di Perangkat Anda:

    • Isi notifikasi - judul dan teks isi yang sudah dirender
    • Riwayat pemicu - kapan notifikasi diterima
    • Nilai variabel - data yang dikirim dalam panggilan webhook
    • Tautan dan metadata - externalLink dan data terkait lainnya

Apa yang Tidak Disimpan

  • Kami tidak menyimpan payload webhook mentah secara permanen
  • Kami tidak mencatat atau menyimpan data sensitif dari permintaan Anda
  • Kami tidak menganalisis atau memproses isi notifikasi untuk tujuan apa pun
  • Kami tidak membagikan data webhook Anda ke pihak ketiga

Rekomendasi Keamanan

  • Perlakukan URL webhook seperti kunci API - URL itu memberi akses tanpa autentikasi untuk mengirim notifikasi
  • Ganti URL secara berkala - gunakan fitur "Reset Token" untuk membuat URL baru
  • Gunakan klien HTTPS - meski kami hanya menerima koneksi HTTPS, pastikan klien Anda memvalidasi sertifikat
  • Validasi sumber webhook - kalau memungkinkan, batasi IP atau layanan mana yang boleh memanggil webhook Anda
  • Awasi penyalahgunaan - perhatikan pola yang tidak biasa atau pemakaian tanpa izin
  • Pisahkan environment - pakai saluran berbeda untuk pengembangan, staging, dan produksi

Pelajari selengkapnya di dokumentasi dukungan kami.

Pemecahan Masalah

Kalau webhook Anda tidak bekerja seperti yang diharapkan, coba langkah diagnosis berikut:

Webhook Tidak Memicu Notifikasi

  1. Pastikan URL webhook-nya benar

    • Salin URL langsung dari aplikasi Echobell
    • Pastikan tidak ada spasi atau karakter tambahan yang ikut tersalin
    • Periksa bahwa Anda memakai https://hook.echobell.one/t/, bukan domain lain

  2. Periksa apakah salurannya aktif

    • Buka saluran itu di aplikasi Echobell
    • Pastikan saluran itu belum dihapus atau diarsipkan
    • Pastikan Anda belum mengatur ulang token webhook-nya (yang akan membatalkan URL tersebut)

  3. Pastikan payload JSON Anda diformat dengan benar (untuk permintaan POST)

    • Gunakan validator JSON untuk memeriksa payload Anda
    • Pastikan setiap string diapit tanda kutip dengan benar
    • Pastikan header Content-Type disetel ke application/json

  4. Pastikan semua variabel yang dibutuhkan templat Anda benar-benar dikirim

    • Periksa templat notifikasi Anda untuk melihat variabel apa saja yang dipakai
    • Pastikan variabel-variabel itu ada di permintaan webhook Anda (parameter query atau body JSON)
    • Ingat bahwa variabel yang hilang akan dirender sebagai string kosong

  5. Periksa apakah salurannya punya pelanggan aktif

    • Notifikasi hanya dikirim kalau ada yang berlangganan saluran tersebut
    • Pastikan langganan Anda ada di daftar saluran pada aplikasi
    • Periksa bahwa langganannya tidak terhapus tanpa sengaja

Notifikasi Dirender dengan Salah

  1. Nama variabel tidak cocok

    • Templat memakai {{server_name}} tetapi webhook mengirim serverName
    • Nama variabel bersifat peka huruf besar-kecil dan harus sama persis
    • Periksa apakah ada salah ketik pada nama variabel

  2. Data bersarang tidak bisa diakses

    • Gunakan notasi titik: {{user.name}} atau notasi kurung siku: {{user["name"]}}
    • Pastikan struktur JSON Anda sesuai dengan yang diharapkan templat
    • Uji dulu dengan variabel datar sederhana, baru tambahkan struktur bersarang

  3. Karakter khusus menimbulkan masalah

    • Lakukan URL-encode pada parameter query dengan benar
    • Escape karakter JSON khusus di body POST
    • Uji dulu dengan teks ASCII sederhana

Menguji Integrasi Anda

Gunakan curl untuk menguji webhook Anda secara langsung:

# Uji dengan parameter query
curl "https://hook.echobell.one/t/<channel-token>?test=hello&status=working"

# Uji dengan body JSON
curl -X POST https://hook.echobell.one/t/<channel-token> \
  -H "Content-Type: application/json" \
  -d '{"test": "hello", "status": "working"}'

Anda seharusnya langsung menerima notifikasi kalau semuanya dikonfigurasi dengan benar.

Masih Bermasalah?

Kalau Anda sudah mencoba langkah-langkah di atas dan tetap mengalami kendala:

  • Kunjungi Pusat Dukungan kami untuk panduan pemecahan masalah lainnya
  • Periksa apakah ada masalah yang sudah diketahui atau pembaruan status layanan
  • Hubungi kami di echobell@weelone.com dengan menyertakan:
    • Deskripsi masalahnya
    • Langkah-langkah yang sudah Anda coba
    • Contoh URL webhook (dengan token dihapus/disamarkan)
    • Contoh payload permintaan
    • Perilaku yang diharapkan versus yang sebenarnya terjadi

Langkah Berikutnya

Setelah Anda memahami integrasi webhook:

Siap mengintegrasikan Echobell dengan sistem Anda? Buat saluran pertama Anda dan mulai terima notifikasi instan!