Stripe webhook’ları: ödemeleri güvenilir biçimde işlemek

Kısaca: Stripe ödemeleri, abonelikleri ve iadeleri bir webhook ile sunucuna bildirir; imzayı doğrularsın, hızlı yanıt verirsin, idempotent işlersin ve müşterinin dönüş sayfasına güvenmezsin.

Biraz daha ayrıntılı: Ödemeden sonra müşteri sitene döner, ancak tarayıcı kapatılabilir veya bağlantı kopabilir. Yalnızca Stripe’ın sunucu mesajı (webhook) güvenilirdir: bir olay içeren HTTP POST (checkout.session.completed, invoice.paid, customer.subscription.deleted …).

Ayrıntılı

Akış

1. Bir uç nokta oluştur (/api/stripe/webhook) ve Stripe’ta (pano veya CLI) olayları seç.
2. Webhook sırrıyla ve ham istek gövdesiyle imzayı doğrula:

const sig = req.headers.get("stripe-signature")!;
const body = await req.text();            // ham, JSON olarak ayrıştırılmamış!
const event = stripe.webhooks.constructEvent(body, sig, process.env.STRIPE_WEBHOOK_SECRET!);

Doğrulama olmadan herkes sahte ödemeler bildirebilir. 3. Olayı işle (siparişi ödenmiş işaretle, abonelik durumunu ayarla, fatura gönder). 4. 2xx ile hızlıca yanıt ver; uzun işi bir kuyruğa/arka plan işine koy.

Güvenilirlik

• Yeniden denemeler: 2xx yanıt vermezsen Stripe yeniden gönderir (birkaç gün boyunca). Kodun idempotent olmalıdır: olay kimliğini (event.id) sakla ve kopyaları yok say; durum geçişlerini kontrol et.
• Sıra garanti edilmez: olaylar yer değiştirmiş gelebilir; gerekirse nesneyi Stripe’tan yeniden çek.
• Veri tabanı kesintisi: o zaman Stripe olayları kaybetmek yerine yeniden denesin diye 5xx yanıt ver. Önce uyanan sunucusuz veri tabanlarında yeterli zaman aşımı bırak.
• Test kipi/canlı kip ayrı sırlara ve uç noktalara sahiptir.
• Yerel test için Stripe CLI (stripe listen --forward-to localhost:3000/api/stripe/webhook).

Güvenlik ve hukuk

Sırrı gizli tut, yalnızca HTTPS, yalnızca gerekli olaylar. Tutarı ve para birimini sunucu tarafında kontrol et, tarayıcıdan alma. Kişisel verileri idareli sakla (kart verilerini Stripe saklar, sen değil: Checkout/Elements ile PCI yükü düşük). Hukuk: cayma bildirimi, faturalar, şartlar, fiyat bilgisi, abonelikler için iptal düğmesi, reşit olmayanlar ve sözleşmeler (ebeveyn onayı). Bu hukuki tavsiye değildir.

Tipik hatalar

• Gövde önceden JSON olarak ayrıştırıldı → imza kontrolü başarısız olur.
• Yanlış sır (test ve canlı, birkaç uç nokta).
• İdempotency yok: yinelenen krediler/e-postalar.
• Çok yavaş yanıt → yeniden deneme seli.
• Yalnızca yönlendirmeye güvenmek.
• Olaylar günlüğe kaydedilmedi: bir olay günlüğü (stripe_events) ile hatalar sonradan izlenebilir. Başarısız teslimatları panoda izle.

Ayrıca bak: Stripe, Webhook’lar, HMAC, İdempotency, Reşit olmayanlar için ödeme hizmetleri