İçeriğe geç
KuryeSoft

Webhook'lar

İmza doğrulama

Webhook adresiniz herkese açıktır; herkes oraya istek gönderebilir. 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.

text
x-kurye-signature = hex( HMAC-SHA256( anahtar = "whsec_...", ileti = ham gövde ) )
  1. Gövdeyi JSON olarak ayrıştırmadan önce ham haliyle okuyun.
  2. Gizli anahtarın tamamıyla (whsec_ ön eki dahil) HMAC-SHA256 hesaplayın.
  3. Sonucu x-kurye-signature başlığıyla sabit süreli karşılaştırmayla eşleştirin (timingSafeEqual, hash_equals, compare_digest).
  4. Tutmuyorsa isteği 401 ile 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.

Gizli anahtar
Değer:whsec_ornekGizliAnahtar1234567890abcde
Ham gövde
Değer:{"event":"webhook.test","sent_at":"2026-11-20T18:10:42.093Z","test":true,"message":"Bu bir deneme çağrısıdır."}
Beklenen imza
Değer:8115be8a79f8b3e057563009ac963061d463566d494cf1c77f8c69ac424ce78d

Gö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:

bash
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_at değ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.status ile kaydedin; aynısı tekrar gelirse işlemeden 200 dö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

Hiçbir istek doğrulanmıyor
Olası sebep:Yanlış anahtar ya da whsec_ ön eki atılmış. Ayrıştırılmış gövdeyle hesaplanıyor.
Türkçe karakterli siparişler doğrulanmıyor
Olası sebep:Gövde UTF-8 dışında bir kodlamayla okunuyor ya da yeniden JSON'a çevriliyor.
Bir süredir doğrulanmıyor
Olası sebep:Gizli anahtar panelde yenilenmiş; firmadan yeni anahtarı isteyin.
Başlık boş geliyor
Olası sebep:Vekil sunucu (proxy) x- başlıklarını siliyor; başlığın uygulamanıza ulaştığını denetleyin.