Webhook keluar — Dokumentasi

Webhook keluar adalah pesan yang dikirim panel ke alamat milik Anda saat sesuatu terjadi pada sebuah akun hosting, agar sistem lain dapat bereaksi: penagihan Anda sendiri, kanal chat, spreadsheet, atau skrip provisioning.

Webhook tersedia untuk administrator dan reseller. Administrator mendapat kabar tentang setiap akun. Reseller hanya mendapat kabar tentang akun milik reseller itu. Pelanggan dan token API tidak dapat membuatnya: webhook diatur di panel itu sendiri, dalam sesi orang yang bersangkutan, agar token yang bocor tidak pernah menjadi aliran tetap peristiwa panel.

Menambahkan satu

Buka halaman keamanan akun Anda (administrator: Keamanan; reseller: Keamanan Login), lalu cari Webhook di bawah token API.

Ketik alamatnya, misalnya https://example.com/hooks/panel.
Centang peristiwa yang Anda inginkan.
Tekan Tambah webhook.

Panel menampilkan secret penandatanganan (diawali whsec_) satu kali saja. Salin sekarang. Secret itu disimpan terenkripsi dan tidak dapat ditampilkan lagi; jika hilang, hapus webhook-nya dan tambahkan yang baru.

Setiap orang dapat memiliki paling banyak 10 webhook.

Alamatnya

Harus diawali https://. http:// biasa ditolak, karena panggilan membawa rincian akun.
Tidak boleh mengandung nama pengguna atau kata sandi. Periksa tanda tangannya saja.
Paling panjang 500 karakter.
Harus berada di internet publik. Alamat di server ini, di jaringan privat, di antarmuka loopback, atau di rentang metadata penyedia cloud ditolak, baik saat Anda menyimpan alamat maupun saat panel benar-benar terhubung (sehingga nama host yang belakangan diarahkan ke alamat privat pun tidak berfungsi).
Pengalihan (redirect) tidak diikuti. Berikan alamat akhirnya.

Peristiwa

Peristiwa	Dikirim saat
`account.created`	Akun hosting dibuat
`account.suspended`	Akun ditangguhkan
`account.unsuspended`	Akun yang ditangguhkan diaktifkan kembali
`account.deleted`	Akun dihapus
`account.activity`	Aktivitas lain pada akun

Tombol Uji pada tiap webhook mengirim peristiwa bernama ping, agar Anda bisa melihat bahwa alamat Anda menjawab. Hanya satu uji yang dapat menunggu pada satu waktu.

Yang dikirim

Setiap panggilan adalah HTTP POST dengan isi JSON:

{
  "event": "account.created",
  "at": "2026-10-23T08:15:00Z",
  "account": { "id": 42, "username": "example", "domain": "example.com" },
  "detail": "short text about what happened"
}

at adalah waktu UTC. Peristiwa ping berbentuk {"event":"ping","at":"…","webhook_id":7}.

Header berikut menyertai setiap panggilan:

Header	Arti
`X-Nimbopanel-Event`	Nama peristiwa, misalnya `account.created`
`X-Nimbopanel-Delivery`	Nomor yang mengidentifikasi pengiriman ini. Percobaan ulang atas pengiriman yang sama memakai nomor yang sama, jadi gunakan untuk mengabaikan duplikat
`X-Nimbopanel-Timestamp`	Kapan panggilan ditandatangani, dalam detik Unix
`X-Nimbopanel-Signature`	`sha256=` diikuti tanda tangan (lihat di bawah)
`Content-Type`	`application/json`
`User-Agent`	`Nimbopanel-Webhook/1`

Memeriksa tanda tangan

Siapa pun dapat mengirim permintaan ke alamat Anda. Tanda tangan adalah cara Anda tahu bahwa sebuah panggilan berasal dari panel Anda.

Tanda tangan adalah HMAC-SHA256, dalam heksadesimal, dari stempel waktu, sebuah titik, dan isi mentah persis seperti yang diterima, dibuat dengan secret penandatanganan Anda:

X-Nimbopanel-Signature == "sha256=" + hex( HMAC_SHA256( secret, X-Nimbopanel-Timestamp + "." + body ) )

Periksa dengan urutan ini:

Hitung nilai di atas dari isi mentah permintaan (sebelum parsing atau pemformatan ulang JSON apa pun).
Bandingkan dengan header memakai perbandingan waktu-konstan.
Tolak panggilan jika stempel waktunya lebih dari 5 menit dari jam Anda. Ini mencegah orang memutar ulang panggilan lama.
Gunakan X-Nimbopanel-Delivery untuk mengabaikan pengiriman yang sudah Anda tangani.

Contoh dalam PHP:

$body = file_get_contents('php://input');
$ts   = $_SERVER['HTTP_X_NIMBOPANEL_TIMESTAMP'] ?? '';
$sig  = $_SERVER['HTTP_X_NIMBOPANEL_SIGNATURE'] ?? '';
$want = 'sha256=' . hash_hmac('sha256', $ts . '.' . $body, $secret);
if (!hash_equals($want, $sig) || abs(time() - (int) $ts) > 300) {
    http_response_code(401);
    exit;
}

Contoh dalam Node.js:

const crypto = require('crypto');
function valid(rawBody, headers, secret) {
  const ts = headers['x-nimbopanel-timestamp'] || '';
  const want = 'sha256=' + crypto.createHmac('sha256', secret).update(ts + '.' + rawBody).digest('hex');
  const got = headers['x-nimbopanel-signature'] || '';
  return got.length === want.length
    && crypto.timingSafeEqual(Buffer.from(got), Buffer.from(want))
    && Math.abs(Date.now() / 1000 - Number(ts)) <= 300;
}

Menjawab, percobaan ulang, dan jeda

Jawab dengan status 2xx apa pun dalam 10 detik. Selain itu dihitung sebagai kegagalan.
Panggilan yang gagal dicoba lagi setelah 1 menit, lalu 5 menit, 30 menit, dan 2 jam. Itu lima kali percobaan seluruhnya, tersebar selama sekitar dua setengah jam, lalu pengiriman ditandai gagal.
Panggilan ke satu alamat dikirim satu per satu, yang tertua lebih dulu. Pengiriman yang menunggu percobaan ulang tidak menahan yang lebih baru, jadi jangan bergantung pada peristiwa yang tiba dengan urutan ketat. Alamat yang lambat hanya menahan dirinya sendiri.
Setelah 50 pengiriman gagal berturut-turut, webhook dijeda: peristiwa baru tidak lagi diantrekan untuknya. Uji yang berhasil menghapus hitungan itu dan peristiwa mengalir lagi.
Paling banyak 200 panggilan yang belum terkirim menunggu untuk satu webhook. Selebihnya, peristiwa berikutnya untuknya tidak diantrekan sampai sebagian terkirim atau gagal.
Panel menyimpan 50 pengiriman selesai terbaru untuk tiap webhook, beserta jawaban yang diterimanya, agar Anda dapat melihat apa yang gagal. Yang paling baru ditampilkan di bawah webhook.

Jika panel menampilkan alasan alih-alih status, alasannya salah satu dari: alamat tidak berada di internet publik, tidak ada jawaban dalam 10 detik, nama host tidak ada, sertifikat HTTPS tidak valid, atau panel tidak dapat terhubung.

Kebiasaan yang baik

Jawab cepat dengan 200 dan kerjakan pekerjaan sebenarnya sesudahnya. Penerima yang butuh lebih dari 10 detik terlihat seperti kegagalan, dan menerima peristiwa yang sama lagi.
Tangani pengiriman yang sama dua kali tanpa masalah. Percobaan ulang dan galat jaringan membuat duplikat mungkin terjadi.
Jauhkan secret dari repositori kode Anda. Jika bocor, hapus webhook-nya dan tambahkan yang baru.

Terkait: Panduan reseller · Mengatasi masalah