Webhook'lar
İmza doğrulama
x-kurye-signature başlığını doğrulayarak isteğin gerçekten kurye firmanızın sunucusundan geldiğinden ve yolda değişmediğinden emin olun.Nasıl hesaplanır
İmza, isteğin ham gövdesinin (bayt bayt, ayrıştırılmadan) webhook kaydının gizli anahtarıyla hesaplanmış HMAC-SHA256 özetidir; küçük harfli onaltılık (hex) olarak 64 karakterdir.
x-kurye-signature = hex( HMAC-SHA256( anahtar = "whsec_...", ileti = ham gövde ) )- Gövdeyi JSON olarak ayrıştırmadan önce ham haliyle okuyun.
- Gizli anahtarın tamamıyla (
whsec_ön eki dahil) HMAC-SHA256 hesaplayın. - Sonucu
x-kurye-signaturebaşlığıyla sabit süreli karşılaştırmayla eşleştirin (timingSafeEqual,hash_equals,compare_digest). - Tutmuyorsa isteği
401ile reddedin ve işlemeyin.
Ayrıştırılmış gövdeyle hesaplamayın
Gövdeyi ayrıştırıp yeniden JSON'a çevirirseniz boşluklar, alan sırası ve Türkçe karakterlerin kodlanışı değişebilir; özet tutmaz. Çatınızın (framework) gövdeyi otomatik ayrıştırmasını bu adres için kapatın ya da ham gövdeye erişin.
Örnekler
Örnekler imzayı doğrular, eski istekleri reddeder ve olayı arka plana bırakıp hemen yanıt verir. Gizli anahtar KURYESOFT_WEBHOOK_SECRET ortam değişkeninden okunur.
// Node.js + Express. Gövde ayrıştırılmadan, ham haliyle okunur (express.raw).
import crypto from "node:crypto";
import express from "express";
const app = express();
const SECRET = process.env.KURYESOFT_WEBHOOK_SECRET; // whsec_...
function validSignature(rawBody, received) {
const expected = crypto.createHmac("sha256", SECRET).update(rawBody).digest("hex");
const a = Buffer.from(expected, "utf8");
const b = Buffer.from(String(received || ""), "utf8");
return a.length === b.length && crypto.timingSafeEqual(a, b);
}
app.post("/kuryesoft/webhook", express.raw({ type: "application/json" }), (req, res) => {
if (!validSignature(req.body, req.get("x-kurye-signature"))) return res.sendStatus(401);
const { event, sent_at: sentAt, order } = JSON.parse(req.body.toString("utf8"));
// 5 dakikadan eski istekleri reddedin (yeniden oynatmaya karşı)
if (Math.abs(Date.now() - Date.parse(sentAt)) > 5 * 60 * 1000) return res.sendStatus(400);
// Olayı kaydedip hemen yanıt verin; ağır işi arka planda yapın
queue.push({ event, order });
res.sendStatus(200);
});
app.listen(3000);Test vektörü
Uygulamanızı aşağıdaki değerlerle sınayın; hesapladığınız özet beklenen değerle aynı olmalıdır.
whsec_ornekGizliAnahtar1234567890abcde{"event":"webhook.test","sent_at":"2026-11-20T18:10:42.093Z","test":true,"message":"Bu bir deneme çağrısıdır."}8115be8a79f8b3e057563009ac963061d463566d494cf1c77f8c69ac424ce78dGövde UTF-8 kodludur ve Türkçe karakterler (ç, ı) olduğu gibi yer alır; ç biçiminde kaçışlanmaz. Komut satırından denemek için:
printf '%s' '{"event":"webhook.test","sent_at":"2026-11-20T18:10:42.093Z","test":true,"message":"Bu bir deneme çağrısıdır."}' \
| openssl dgst -sha256 -hmac 'whsec_ornekGizliAnahtar1234567890abcde'Yeniden oynatmaya karşı
İmza gövdeyi korur, ancak zaman damgası içermez: ele geçirilmiş geçerli bir istek daha sonra yeniden gönderilebilir. Bunu önlemek için:
- Gövdedeki
sent_atdeğeri (isteğin gönderildiği an) 5 dakikadan eskiyse isteği reddedin. Sunucunuzun saatinin doğru olduğundan emin olun (NTP). - İşlediğiniz olayları
order.id+event+order.statusile kaydedin; aynısı tekrar gelirse işlemeden200dönün. - Webhook adresiniz yalnızca HTTPS olsun.
Gizli anahtarı yenilemek
Kurye firması paneldeki Gizli anahtarı yenile seçeneğiyle yeni bir anahtar üretebilir. Eski anahtar hemen geçersiz olur ve sonraki olaylar yeni anahtarla imzalanır. Kesinti olmaması için yenilemeyi firmayla birlikte yapın ve yeni anahtarı hemen sisteminize yükleyin. Geçiş sırasında kısa süre iki anahtarı da kabul eden bir doğrulama yazabilirsiniz.
İmza tutmuyorsa
whsec_ ön eki atılmış. Ayrıştırılmış gövdeyle hesaplanıyor.x- başlıklarını siliyor; başlığın uygulamanıza ulaştığını denetleyin.