Webhook nedir? Güvenilir ve güvenli bir webhook sistemi nasıl tasarlanır?

Webhook, bir olay gerçekleştiğinde sistemin karşı tarafa HTTP POST ile bildirim göndermesidir ("bizi aramayın, biz sizi ararız"). İstemcinin sürekli polling yapmasına gerek bırakmaz. Örnek: ödeme sağlayıcısının payment.succeeded olayını sizin /webhooks/payments adresinize göndermesi.

Gönderen taraf (provider)

• İmza: gövdeyi paylaşılan bir secret ile HMAC-SHA256 imzalayıp başlıkta gönderin.
• Timestamp: imzaya zaman damgasını dahil edin; alıcı eski istekleri reddederek replay saldırısını önler.
• Retry: 2xx dışı yanıt veya timeout'ta exponential backoff ile yeniden deneyin (ör. 1 dk, 5 dk, 30 dk ... 24 saat).
• Event ID: her olaya benzersiz ID verin.
• Başarısız teslimatları görüntüleyip elle yeniden göndermeye imkân tanıyın.

Alan taraf (consumer)

app.post("/webhooks/payments", express.raw({ type: "application/json" }), async (req, res) => {
  const imza = req.header("X-Signature");
  const beklenen = crypto.createHmac("sha256", SECRET).update(req.body).digest("hex");
  if (!imza || !crypto.timingSafeEqual(Buffer.from(imza), Buffer.from(beklenen))) {
    return res.sendStatus(401);
  }
  const olay = JSON.parse(req.body);
  await kuyruk.ekle(olay);   // ağır işi sonra yap
  res.sendStatus(200);       // hızlıca onayla
});

1. İmzayı ham gövde üzerinden doğrulayın; parse edilip yeniden serialize edilmiş JSON farklı olabilir.
2. Hızlıca 2xx dönün, asıl işi kuyrukta yapın; aksi hâlde timeout ve gereksiz retry oluşur.
3. Idempotent olun: retry nedeniyle aynı olay birden çok kez gelebilir (at-least-once). İşlenen event ID'lerini saklayıp tekrarları atlayın.
4. Sıralamaya güvenmeyin; olaylar sırasız gelebilir. Gerekirse kaynağın güncel durumunu API'den çekin.