Lewati ke konten
HNROS Pusat Bantuan
Bahasa Indonesia
Mulai gratis
Daftar isiMembuat langgananPeristiwaIsi notifikasiMemverifikasi tanda tanganPengiriman, percobaan ulang, dan surat matiLog pengiriman dan kirim ulangKunci enkripsi serverRingkasan endpoint OpenAPIDi ponsel

Webhook dan OpenAPI: notifikasi peristiwa ke sistem lain

Saat terjadi peristiwa di HNR (faktur dicatat, pesanan dihapus, pengiriman berangkat…), webhook mengirim notifikasi HTTP bertanda tangan ke alamat yang Anda tetapkan. Notifikasi hanya membawa ringkasan dokumen dan tautan API-nya; penerima membaca catatan lengkap dari API dengan sesinya sendiri. Halaman ini menjelaskan kontrak, bukan skema resmi.

Membuat langganan

Pengaturan › Integrasi dan webhook hanya terbuka bagi administrator sistem. Langganan baru memerlukan nama, alamat tujuan, dan minimal satu peristiwa. Alamat harus diawali https; tujuan di jaringan lokal atau di komputer ini (mis. 192.168.x.x, localhost) hanya diterima bila kotak persetujuan administrator dicentang. Langganan kedua untuk alamat yang sama tidak dapat dibuat.

Filter opsional: hanya kontak atau gudang tertentu. Jika filter ditetapkan dan dokumen tidak memiliki kolom itu, notifikasi tidak dikirim. Jumlah dan mata uang dokumen hanya dikirim bila “Tambahkan jumlah dan mata uang dokumen ke notifikasi” dicentang.

Saat disimpan, kunci rahasia (diawali whsec_) hanya ditampilkan sekali; simpan di sistem penerima. Kunci disimpan terenkripsi di server dan tidak dapat dibaca lagi. Jika hilang, buat yang baru dengan “Perbarui kunci”; tanda tangan dengan kunci lama tidak lagi valid.

Peristiwa

faktur, pesanan, penawaran (fatura, siparis, teklif): yazildi, degisti, silindi · surat jalan (irsaliye): yazildi, silindi · kuitansi (makbuz): yazildi, degisti, silindi · stok.hareket (transfer antar gudang dikirim, diterima atau susut; persetujuan stok opname) · sevkiyat.durum (berangkat, perhentian diterima, koreksi POD) · onay.karar · dof.acildi · servis.bilet (dibuka, status) · uretim.teyit (konfirmasi atau pembatalan). Kode peristiwa ada di header X-HNR-Event dan di kolom olay pada isi; tombol uji mengirim test.ping.

Isi notifikasi

POST https://alici.ornek.com/hnr
Content-Type: application/json; charset=utf-8
User-Agent: HNR-Webhook/1
X-HNR-Event: fatura.yazildi
X-HNR-Delivery: wh_2
X-HNR-Timestamp: 1791559000
X-HNR-Signature: t=1791559000,v1=5f1c…(64 hex)

{"surum":1,"id":"ev_3fa1…","olay":"fatura.yazildi","firma":"ornek","zaman":"2026-10-09T15:15:00.000Z",
 "belge":{"tur":"fatura","sira":9107041,"no":"SF2026000126","cari":"C001","depo":"MERKEZ","tarih":"2026-10-09","tutar":360},
 "baglanti":"/api/fatura/9107041"}

belge.no adalah nomor dokumen final; catatan lengkap dibaca dari API lewat baglanti. tutar dan doviz hanya ada pada langganan yang menyertakan jumlah; tanpa doviz jumlah dalam mata uang lokal perusahaan. Untuk peristiwa hapus, ringkasan dibaca sebelum dokumen dihapus. surum adalah versi format muatan: kolom baru bisa ditambah, kolom lama tidak berubah.

Memverifikasi tanda tangan

Setiap permintaan membawa header X-HNR-Event, X-HNR-Delivery (ID pengiriman), X-HNR-Timestamp, dan X-HNR-Signature: t=…,v1=…. v1 adalah HMAC-SHA256 (heksadesimal) dari teks t + "." + isi mentah dengan kunci rahasia. Penerima sebaiknya memverifikasi tanda tangan dengan perbandingan waktu-konstan, menolak waktu lebih dari 5 menit, dan tidak memproses X-HNR-Delivery yang sama dua kali namun tetap menjawab 2xx (perlindungan pengulangan).

// Node.js (express.raw ile ham gövde / raw body)
import { createHmac, timingSafeEqual } from 'node:crypto';
const seen = new Set();
export function verify(secret, headers, rawBody) {
  const p = Object.fromEntries(String(headers['x-hnr-signature']).split(',').map((x) => x.split('=')));
  if (Math.abs(Date.now() / 1000 - Number(p.t)) > 300) return 'old';
  const expected = createHmac('sha256', secret).update(`${p.t}.${rawBody}`).digest();
  const got = Buffer.from(p.v1 || '', 'hex');
  if (got.length !== expected.length || !timingSafeEqual(got, expected)) return 'bad';
  const id = headers['x-hnr-delivery'];
  if (seen.has(id)) return 'duplicate';   // answer 2xx, do not process again
  seen.add(id); return 'ok';
}
# Python 3
import hmac, hashlib, time
def verify(secret: str, signature: str, raw_body: bytes) -> bool:
    p = dict(x.split('=', 1) for x in signature.split(','))
    if abs(time.time() - int(p['t'])) > 300:
        return False
    expected = hmac.new(secret.encode(), p['t'].encode() + b'.' + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, p.get('v1', ''))

Pengiriman, percobaan ulang, dan surat mati

HNR melakukan POST ke alamat Anda dan menunggu 10 detik; hanya jawaban 2xx yang dihitung terkirim dan pengalihan tidak diikuti. Setelah percobaan gagal, jeda berturut-turut sekitar 1 mnt, 3 mnt, 11 mnt, 38 mnt, 2 jam, 7 jam, dan 24 jam. Jika delapan percobaan gagal, pengiriman menjadi surat mati. Notifikasi untuk langganan dan dokumen yang sama dikirim berurutan: yang berikutnya tidak dikirim sebelum pengiriman sebelumnya selesai. Per perusahaan paling banyak 4 pengiriman berjalan bersamaan.

Tanpa langganan server tidak mengirim apa pun. Pengiriman berjalan tiap menit di perusahaan milik server; di perusahaan lain berjalan setiap ada transaksi baru di perusahaan itu. Pada langganan yang dihentikan, notifikasi tertunda menunggu dan dikirim setelah diaktifkan kembali.

Log pengiriman dan kirim ulang

Log pengiriman menampilkan status setiap notifikasi (menunggu, terkirim, surat mati), jumlah percobaan, dan kode HTTP terakhir; rinciannya memuat isi yang dikirim, 1 KB pertama respons, dan setiap percobaan. “Kirim ulang” langsung mengirim notifikasi sekali lagi dengan ID pengiriman yang sama; jika gagal, aturan percobaan ulang dimulai dari awal. Catatan tidak pernah dihapus. “Kirim uji” mengirim peristiwa test.ping ke alamat langganan.

Kunci enkripsi server

Kunci rahasia disimpan dengan AES-256-GCM memakai kunci enkripsi server yang sama dengan koneksi bank langsung (HNR_BANKA_KIMLIK_ANAHTARI). Jika kunci ini belum ditetapkan, langganan tidak dapat disimpan. Jika kunci berubah, kunci rahasia tersimpan tidak dapat didekripsi dan setiap langganan perlu “Perbarui kunci”.

Ringkasan endpoint OpenAPI

GET /api/openapi.json (atau tombol unduh di bagian Integrasi) mencantumkan semua endpoint API yang sedang dibuka server, dengan path, metode, dan label modul. Isi permintaan dan respons tidak didokumentasikan: ini ringkasan endpoint, bukan skema resmi. Autentikasi: kunci API Authorization: Bearer dan X-Oturum-Token.

Di ponsel

Di ponsel, langganan tampil sebagai kartu; langganan baru dibuat dalam tiga langkah (Alamat, Peristiwa, Filter). Log pengiriman berupa daftar kartu; setiap kartu punya tombol Detail dan Kirim ulang.

Panduan terkait