hikiehikieDeveloper Documentation
Nasıl çalışır

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

KuralNeden
Ortam değişkeninde tutunKod deposuna düşerse deponun tüm okuyucuları sipariş uydurabilir
İstemciye göndermeyinTarayıcıya ya da mobil uygulamaya inen bir secret, secret değildir
Loglara yazmayınLog 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/8f3c1a92be04d5e7

Bu, imzanın yerine geçmez — yanına eklenir.

Bu sayfada