Saat mengintegrasikan webhook (payment gateway, marketplace, layanan pengiriman, dan sebagainya), kita hampir selalu diminta memverifikasi signature: hitung HMAC-SHA256 dari body request dengan secret key, lalu bandingkan dengan nilai di header. Masalah klasiknya: rumusnya sudah benar, tetapi hasilnya tetap tidak cocok.
Dalam banyak kasus, penyebabnya bukan algoritmanya, melainkan format penulisannya. HMAC-SHA256 menghasilkan 32 byte biner. Byte yang sama itu bisa ditulis sebagai hex (64 karakter) atau Base64 (44 karakter). Kalau server mengirim Base64 sementara kode kita membandingkan dengan hex, hasilnya pasti beda walaupun byte-nya identik.
Semua secret, body, dan signature di artikel ini adalah contoh fiktif. Jangan pernah menempelkan secret key asli ke alat online mana pun, termasuk alat buatan saya.
Contoh perhitungan
Data ilustratif:
- Secret:
rahasia-contoh-123 - Body (39 byte, persis seperti ini, tanpa spasi):
{"order_id":"INV-0001","amount":150000}
Hasil HMAC-SHA256 (32 byte), ditulis dalam dua format:
hex : 8a82c1eae9c036d5f2a58c1365374b859890fdd41938d5c1dfc7a976e98a6c4a (64 karakter)
Base64 : ioLB6unANtXypYwTZTdLhZiQ/dQZONXB38epdumKbEo= (44 karakter)
Kenapa panjangnya segitu?
- Hex: setiap byte menjadi 2 karakter → 32 × 2 = 64.
-
Base64: setiap 3 byte menjadi 4 karakter. 32 byte = 10 kelompok penuh (30 byte → 40 karakter) + sisa 2 byte → 4 karakter dengan satu
=sebagai padding → 44 (RFC 4648).
Jadi, kalau signature di header berakhiran = dan panjangnya 44, hampir pasti itu Base64 dari 32 byte. Kalau panjangnya 64 dan isinya hanya 0–9 dan a–f, itu hex.
Kode verifikasi (Node.js dan Python)
Node.js:
const crypto = require("crypto");
function verify(rawBody, headerSig, secret) {
const digest = crypto.createHmac("sha256", secret).update(rawBody).digest(); // Buffer 32 byte
// Dekode signature dari header sesuai formatnya, lalu bandingkan BYTE, bukan string
const received = /^[0-9a-f]{64}$/i.test(headerSig)
? Buffer.from(headerSig, "hex")
: Buffer.from(headerSig, "base64");
return received.length === digest.length && crypto.timingSafeEqual(received, digest);
}
Python:
import hmac, hashlib, base64
def verify(raw_body: bytes, header_sig: str, secret: bytes) -> bool:
digest = hmac.new(secret, raw_body, hashlib.sha256).digest()
expected = base64.b64encode(digest).decode() # atau digest.hex() jika server memakai hex
return hmac.compare_digest(expected, header_sig)
Dengan data contoh di atas, versi Python mengembalikan True untuk ioLB6unANtXypYwTZTdLhZiQ/dQZONXB38epdumKbEo=. Gunakan perbandingan constant-time (timingSafeEqual / compare_digest), bukan ==.
4 jebakan yang paling sering
1. Meng-Base64-kan string hex.
Ini kesalahan paling umum. Kode menghitung digest('hex'), lalu hasilnya di-encode lagi ke Base64 sebagai teks. Hasilnya OGE4MmMxZWFl... dengan panjang 88 karakter, bukan 44. Yang benar: Base64 dari byte digest, bukan dari teks hex-nya. Kalau Anda melihat signature 88 karakter, kemungkinan besar terjadi encode ganda.
2. Body yang di-parse lalu di-serialize ulang.
HMAC dihitung dari byte mentah. Kalau framework mem-parse JSON lalu Anda melakukan JSON.stringify lagi, spasi atau urutan key bisa berubah. Body contoh yang ditulis dengan spasi setelah titik dua dan koma ({"order_id": "INV-0001", "amount": 150000}, 42 byte) menghasilkan signature yang sama sekali berbeda: h/dO3EGSEM7hOpG5XfvE+KuHAnzIszIscN7L3YnLcOA=. Simpan dan pakai raw body.
3. Huruf besar/kecil dan pemisah pada hex.
8A82C1... dan 8a82c1... adalah byte yang sama, tetapi perbandingan string biasa akan menganggapnya berbeda. Begitu juga format 8a:82:c1:... atau yang dipisah spasi. Bandingkan byte-nya, atau normalisasi dulu (hapus pemisah, ubah ke huruf kecil).
4. Base64 vs Base64URL.
Sebagian sistem mengirim varian URL-safe: + menjadi -, / menjadi _, dan = dihapus. Signature contoh kita menjadi ioLB6unANtXypYwTZTdLhZiQ_dQZONXB38epdumKbEo (43 karakter). Byte-nya tetap sama. Dekode dengan decoder yang mendukung Base64URL sebelum membandingkan.
Cek cepat dengan konverter (tanpa menulis kode)
Untuk debugging, saya membuat konverter gratis yang bekerja dua arah: Konverter Hex ↔ Base64. Saya sendiri yang membuat base64decodetool.com. Konversinya berjalan di browser.
- Pilih tab Hex to Base64, lalu tempel hex hasil log Anda (gunakan contoh fiktif atau signature yang tidak sensitif, jangan secret key-nya).
- Lihat hasil di Base64 Output dan bandingkan dengan header. Untuk contoh di atas, hasilnya
ioLB6unANtXypYwTZTdLhZiQ/dQZONXB38epdumKbEo=(44 chars). - Untuk arah sebaliknya, klik Base64 to Hex (atau Tukar Input). Varian Base64URL juga diterima.
Beberapa catatan jujur tentang alat ini:
- Hasil arah Base64 → Hex ditampilkan dalam huruf besar dan dipisah spasi (
8A 82 C1 ...). Hapus spasinya dan abaikan huruf besar/kecil saat membandingkan. - Awalan
0xsaat ini tidak dibuang secara otomatis, sehingga muncul error "Length must be even". Hapus0xsecara manual sebelum menempel. - Beberapa label (misalnya "Hex String Input", "Base64 Output") masih berbahasa Inggris.
Ringkasan
| Yang terlihat di header | Kemungkinan format |
|---|---|
| 64 karakter, 0–9 a–f | hex dari SHA-256 |
44 karakter, berakhiran =
|
Base64 dari 32 byte |
43 karakter, ada - atau _
|
Base64URL tanpa padding |
| 88 karakter | Base64 dari teks hex (encode ganda) |
Base64 dan hex hanyalah cara menulis byte, bukan enkripsi. Keamanan signature sepenuhnya bergantung pada kerahasiaan secret key dan perbandingan yang benar. Ikuti selalu dokumentasi resmi penyedia webhook Anda untuk format header, algoritma, dan data apa saja yang ditandatangani.
Referensi: RFC 2104 (HMAC), https://www.rfc-editor.org/rfc/rfc2104 · RFC 4648 (Base64 & Base64URL), https://www.rfc-editor.org/rfc/rfc4648. Semua nilai contoh dihitung ulang dengan Node.js crypto, Python hmac, dan logika JavaScript asli konverter ini.
Top comments (0)