Güvenlik
İmza modeli, secret yönetimi, HTTPS zorunluluğu ve adres kısıtları.
İmza neden var
Webhook endpoint'iniz internete açık bir adrestir. Adresini bilen herkes size
POST atabilir. İmza olmadan, sahte bir "sipariş ödendi" isteğiyle bedava
ürün alınabilir.
İmza bunu çözer: gövde, yalnızca sizin ve hikie'nin bildiği bir secret ile HMAC-SHA256 kullanılarak imzalanır. Secret'ı bilmeyen biri geçerli bir imza üretemez.
İmza formülü
Hikie-Signature = HMAC_SHA256(secret, "<Hikie-Timestamp>.<ham gövde>")Sonuç küçük harfli hex olarak Hikie-Signature başlığında gönderilir.
Zaman damgasının imzaya dahil edilmesi tekrar oynatma (replay) koruması sağlar: saldırgan geçerli imzalı eski bir isteği yakalayıp tekrar gönderemesin diye, siz zaman damgasının kabul penceresinde olduğunu doğrularsınız.
rawBody gövdenin ham hâli olmalı. JSON'a çevirip yeniden serileştirmek
(JSON.stringify(req.body)) baytları değiştirir ve imzayı bozar.
Uygulama örnekleri: İmza doğrulama.
Üç kontrol
Doğru bir doğrulama üç adımdan oluşur; hiçbirini atlamayın.
Zaman damgası penceresi
Hikie-Timestamp ile kendi saatiniz arasındaki fark makul mü? Önerilen
tolerans ±5 dakika. Bu, yakalanmış bir isteğin sonsuza kadar
kullanılmasını engeller.
İmza eşleşmesi
Hesapladığınız HMAC ile gelen imzayı sabit zamanlı karşılaştırın
(crypto.timingSafeEqual, hash_equals, hmac.compare_digest). Sıradan
=== karşılaştırması, ilk farklı bayta kadar geçen süre üzerinden imzayı
tahmin etmeye kapı aralar.
Tekrar kontrolü
Hikie-Webhook-Id daha önce işlendiyse tekrar işlemeyin. Bkz.
Tekrarları yönetmek.
Secret yönetimi
| Kural | Neden |
|---|---|
| Ortam değişkeninde tutun | Kod deposuna düşerse deponun tüm okuyucuları sipariş uydurabilir |
| İstemciye göndermeyin | Tarayıcıya ya da mobil uygulamaya inen bir secret, secret değildir |
| Loglara yazmayın | Log toplama sistemleri genelde daha az korunur |
| Her abonelik için ayrı | Bir secret sızarsa yalnızca o abonelik etkilenir |
Secret yalnızca oluşturma anında bir kez gösterilir. hikie onu şifreli
saklar ve bir daha düz metin olarak göstermez — panelde yalnızca son 4
karakterini maskeli görürsünüz (whsec_…92be).
Secret'ı yenilemek
Panelde Secret'ı yenile yeni bir secret üretir ve size bir kez gösterir.
Yenileme anında geçerli olur; eski secret o saniyeden itibaren geçersizdir. Geçiş süresi yoktur. Sunucunuzdaki değeri güncelleyene kadar gelen istekler imza doğrulamanızdan geçemez.
Kesintisiz geçiş istiyorsanız önerilen yol: sunucunuzu iki secret'ı da kabul edecek şekilde geçici olarak ayarlayın, yenilemeyi yapın, yeni değeri yayınlayın, sonra eskisini kaldırın.
const SECRETS = [process.env.HIKIE_WEBHOOK_SECRET, process.env.HIKIE_WEBHOOK_SECRET_OLD]
.filter(Boolean);
const valid = SECRETS.some((secret) => signatureMatches(secret, timestamp, rawBody, signature));Ne zaman yenilemelisiniz:
- Secret sızdığından şüpheleniyorsanız
- Sunucuya erişimi olan biri ekipten ayrıldıysa
- Periyodik olarak (yılda bir makul bir alışkanlıktır)
HTTPS zorunlu
Yalnızca https:// adresler kabul edilir. Gerekçe: imza gövdenin
değiştirilmediğini kanıtlar ama gövdeyi gizlemez. Düz HTTP üzerinden
müşteri adı, e-posta ve sipariş tutarı yol boyunca okunabilir olurdu.
Sertifikanız geçerli olmalı — süresi dolmuş, kendinden imzalı ya da alan adıyla
eşleşmeyen sertifikalar tls hatası verir.
Yönlendirme takip edilmez
301/302/307 yanıtları takip edilmez ve kalıcı hata sayılır.
Bu bir eksiklik değil, güvenlik kararı: yönlendirme hedefi kontrol
edilmediğinden, https://ornek.com/hook adresinin özel bir iç ağ adresine
yönlendirmesi tüm adres kontrollerini atlatırdı.
Pratik sonuç: abonelikte nihai adresi yazın. www yönlendirmesi olan bir
alan adında https://ornek.com/hook değil https://www.ornek.com/hook yazın.
Kabul edilmeyen adresler
Webhook URL'sini siz belirlediğiniz için, hikie sizin seçtiğiniz adrese istek atan bir vekil hâline gelir. Bunun kötüye kullanılmaması için şu hedefler reddedilir:
https:dışındaki şemalar (http:,file:,ftp:…)- URL içinde kullanıcı adı/şifre (
https://user:pass@host/) localhost,*.localhost,*.internal,*.local- Özel ağ adresleri:
10.0.0.0/8,172.16.0.0/12,192.168.0.0/16 - Loopback:
127.0.0.0/8,::1 - Link-local:
169.254.0.0/16(bulut metadata servisleri),fe80::/10 - Operatör NAT'ı:
100.64.0.0/10 - Multicast ve ayrılmış aralıklar
- IPv6 ULA (
fc00::/7) ve IPv4-eşlemli biçimler (::ffff:127.0.0.1)
Kontrol iki noktada yapılır: aboneliği kaydederken (hatayı hemen görürsünüz) ve her gönderim anında (adres sonradan değişmiş olabilir). Ayrıca bağlantı kurulurken alan adının çözümlendiği IP de doğrulanır.
Reddedilen bir hedef kalıcı hata sayılır ve abonelik hızla failing durumuna
düşer; nedeni panelde yazar.
Sabit IP adresi
hikie'nin giden istekleri sabit bir IP aralığından gelmez. Güvenlik duvarınızı IP'ye göre yapılandırmayın; kimlik doğrulamasını imza üzerinden yapın.
Endpoint'inizi ek olarak korumak istiyorsanız tahmin edilmesi zor bir yol kullanın:
https://sunucunuz.com/hikie/webhook/8f3c1a92be04d5e7Bu, imzanın yerine geçmez — yanına eklenir.