Langsung ke konten utama
Webhook memungkinkan AgencyHandy mendorong data ke sistem eksternal Anda saat sesuatu berubah — tidak perlu polling. Ketika peristiwa yang dikonfigurasi terjadi (misalnya, pesanan diperbarui atau tiket dukungan dibuat), AgencyHandy mengirimkan permintaan HTTP POST dengan payload JSON ke URL endpoint yang Anda tentukan. Ini memudahkan sinkronisasi alat eksternal seperti CRM, sistem penagihan, atau dasbor kustom dengan workspace AgencyHandy Anda secara real-time.
Workspace paket Business Pro mendukung hingga 30.000 peristiwa webhook per periode penagihan. Periksa batas paket Anda sebelum mengatur otomasi bervolume tinggi.

​
Peristiwa yang didukung

Anda dapat berlangganan webhook untuk kombinasi peristiwa berikut:
KategoriPeristiwa
LayananDibuat, Diperbarui, Dihapus
PesananDibuat, Diperbarui, Dihapus
TugasDibuat, Ditetapkan, Diselesaikan, Diperbarui
TagihanStatus berubah
Klien / PenggunaKlien baru ditambahkan, Klien/pengguna dihapus
ProposalDikirim, Diterima, Disetujui, Ditolak
TiketDibuat, Ditetapkan, Status berubah
PembayaranDiterima, Gagal
Paket LayananDibuat, Diperbarui, Dihapus

​
Buat webhook

1

Navigasi ke Webhook Management

Di bilah sisi kiri, pergi ke Integrations → Webhooks Management.
2

Autentikasi token Anda

Klik tombol Management untuk mengautentikasi token webhook Anda. Token ini digunakan untuk menandatangani payload keluar sehingga Anda dapat memverifikasi bahwa payload tersebut berasal dari AgencyHandy.
3

Buat webhook baru

Klik Create New Webhook untuk membuka formulir konfigurasi webhook.
4

Masukkan URL endpoint

Di kolom Endpoint URL, masukkan URL sistem eksternal yang seharusnya menerima data webhook. URL ini harus berupa endpoint POST yang dapat diakses publik.
5

Pilih tipe konten

Pilih JSON sebagai tipe konten. AgencyHandy mengirim semua payload webhook sebagai application/json.
6

Pilih peristiwa webhook

Pilih setiap peristiwa yang harus memicu webhook ini. Anda dapat memilih peristiwa dari beberapa kategori — misalnya, Order: Created dan Invoice: Status changed keduanya dapat mengarah ke endpoint yang sama.
7

Aktifkan webhook

Aktifkan tombol radio Active. Saat aktif, AgencyHandy mengirimkan payload untuk semua peristiwa yang dipilih ke endpoint Anda secara real-time.
8

Simpan konfigurasi

Tinjau pengaturan Anda, lalu klik Save. Webhook muncul dalam daftar dan mulai mengirimkan peristiwa segera.

​
Uji webhook

Setelah membuat webhook, kirimkan payload uji untuk mengonfirmasi bahwa endpoint Anda dapat dijangkau dan memproses data dengan benar.
1

Buka webhook

Dari daftar Webhooks Management, klik webhook yang ingin Anda uji.
2

Klik Test Event

Klik tombol Test Event di halaman detail webhook.
3

Pilih peristiwa uji

Pilih peristiwa contoh dari daftar peristiwa yang dikonfigurasi pada webhook ini (misalnya, Order: Created).
4

Kirim payload uji

Klik Send. AgencyHandy mengirimkan payload contoh ke URL endpoint Anda.
5

Verifikasi hasilnya

Periksa sistem eksternal Anda untuk mengonfirmasi payload uji telah tiba dan diproses sebagaimana mestinya. Kembali di AgencyHandy, klik ke webhook untuk meninjau riwayat — Anda dapat melihat permintaan lengkap, respons yang dikembalikan endpoint Anda, dan mengirim ulang peristiwa masa lalu jika diperlukan.
Gunakan alat seperti Webhook.site atau RequestBin sebagai endpoint sementara selama pengaturan untuk memeriksa bentuk payload yang tepat sebelum menghubungkan sistem nyata Anda.

​
Autentikasi payload webhook

Setiap permintaan webhook keluar dari AgencyHandy menyertakan header tanda tangan yang dapat digunakan endpoint Anda untuk memverifikasi bahwa payload tersebut asli dan tidak dirusak.

​
Header tanda tangan

x-ah-sig: <signature>
AgencyHandy menambahkan header ini ke setiap permintaan webhook. Ekstrak nilai dari permintaan masuk dan teruskan ke endpoint verifikasi.

​
Verifikasi tanda tangan webhook

Kirim permintaan berikut untuk mengonfirmasi bahwa payload adalah asli: 
POST https://api.agencyhandy.com/api/v1/webhooks/verify-signature
Content-Type: application/json
​
webhookId
string
wajib
ID webhook yang menerima peristiwa. Temukan ini di halaman detail webhook di AgencyHandy.
​
signature
string
wajib
Nilai header x-ah-sig dari permintaan webhook yang masuk.
​
secret
string
wajib
Rahasia webhook yang ditampilkan di halaman detail webhook di AgencyHandy.
​
payload
object
wajib
Isi JSON mentah yang diterima dari permintaan webhook AgencyHandy.
const url = 'https://api.agencyhandy.com/api/v1/webhooks/verify-signature';

const postData = {
  webhookId: 'your_webhook_id',
  signature: 'your_signature',   // value of x-ah-sig header
  secret: 'your_webhook_secret',
  payload: {},                   // the parsed JSON body from AgencyHandy
};

const response = await fetch(url, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(postData),
});

const data = await response.json();
console.log(data); // { "verification_status": "SUCCESS" }
Respons
​
verification_status
string
SUCCESS ketika tanda tangan valid. FAILED ketika verifikasi gagal (HTTP 403).
Success (200)
{
  "verification_status": "SUCCESS"
}
Failure (403)
{
  "type": "PermissionError",
  "status": 403,
  "verification_status": "FAILED"
}
Jaga kerahasiaan rahasia webhook Anda. Rotasi secara berkala dan perbarui logika verifikasi Anda segera setelah rotasi. Jangan pernah mengeksposnya dalam kode sisi klien atau repositori publik.

​
Catatan penting

  • URL endpoint Anda harus berupa URL POST HTTPS yang dapat diakses publik.
  • Jika endpoint Anda sementara tidak tersedia, periksa panel riwayat webhook di AgencyHandy — Anda dapat mengirim ulang peristiwa masa lalu langsung dari sana.
  • Pantau aktivitas webhook secara rutin untuk mendeteksi pengiriman yang gagal atau upaya akses tidak sah.
  • Webhook yang berulang kali gagal dapat dijeda oleh AgencyHandy — tinjau log pengiriman untuk mendeteksi masalah lebih awal.