Bir müşteri ödeme yaptığında, Stripe arka ucunuza bir `payment_intent.succeeded` olayı gönderir ve uç noktanızın siparişi ödenmiş olarak işaretlemesi gerekir. Bu son adım, sessizce bozulan adımdır. Web kancası gelir, işleyiciniz hata fırlatır ve bir destek bileti "Ödedim ama hesabım hala ödenmemiş görünüyor" diyene kadar kimse fark etmez. Her dağıtımda, olayın geldiğini ve doğru şekilde işlendiğini kanıtlayan bir CI testi istersiniz. İşin püf noktası, bir web kancasının Stripe'tan size gelen bir HTTP çağrısı olması, sizin yaptığınız bir istek olmamasıdır. Çoğu API test aracı, bir istek göndermek ve yanıtı kontrol etmek için tasarlanmıştır, ki bu tam tersi bir yapıdır. Bu nedenle soru şu hale gelir: bir insan izlemeden, bir CI çalışması içinde, kendi zamanlamasında gelen bir şeyi nasıl doğrulayabilirsiniz? Bu kılavuz, bunu Apidog ile yapmanın dürüst ve desteklenen yolunu gösteriyor ve önceden bilmeniz gereken bir sınırlamayla başlıyor. Önce olay odaklı uç noktaları test etmenin daha geniş resmini görmek isterseniz, web kancaları nasıl test edilir hakkındaki kılavuzumuz zemin hazırlar ve Stripe'ın kendi web kancası belgeleri olay teslim modelini kapsar.
Çevresinde tasarım yapmanız gereken kısıtlama
İşte Apidog'un kendi belgelerinde açıkça belirtilen temel gerçek: "ApiDog doğal olarak web kancalarını dinlemeyi desteklemez." Apidog, genel bir URL'de oturup Stripe'ın gelen çağrılarını gerçek zamanlı olarak yakalamaz. Stripe'ı bir Apidog dinleyicisine yönlendirip olayların akışını izlemeyi umuyorsanız, bu yol mevcut değildir.
Bu bir çıkmaz sokak gibi görünüyor. Ama değil. Sadece testin şeklini değiştirir. Web kancasını gelirken engellemek yerine, onu kendi arka ucunuzda yakalar, depolarsınız ve ardından Apidog'un o depolanmış kaydı sorgulamasını ve üzerinde doğrulama yapmasını sağlarsınız. Önce yakala, sonra doğrula. Bu ayrımı kabul ettiğinizde, tüm iş akışı basitleşir ve önemlisi, bir veritabanı sorgusu deterministik ve tekrarlanabilir olduğu için CI'a mükemmel uyum sağlar.
Yakala-sonra-sorgula modelinin nasıl göründüğü
Apidog'un belgelerinde önerilen modelin dört hareketli parçası vardır:
- Gelen Stripe web kancalarını yakalamak için arka uç hizmetinizde bir uç nokta oluşturun.
- Web kancası olay verilerini veritabanınızdaki bir
Stripe event logstablosunda saklayın. - Veritabanınızı sorgulamak için Apidog'un İstek Sonrası İşleyicisini (Post-Request Processor) kullanın.
- Depolanan web kancası olayını alın ve beklenen sonuçlara göre doğrulayın.
Bu adımların ikisi kodunuzda, ikisi Apidog'da yer alır. Yakalama uç noktası ve günlükleme tablosunu inşa etmek sizin sorumluluğunuzdadır, çünkü bunlar kendi uygulamanız içinde çalışır. Apidog'un işi, olay veritabanınıza girdiğinde başlar: o veritabanına bağlanır ve olayın beklediğiniz gibi işlendiğini doğrulamak için satırı geri okur. Bu ayrımı net tutun, gerisi yerine oturacaktır.
Adım 1: Yakalama uç noktasını oluşturun
Arka ucunuzun Stripe'ın POST isteği gönderebileceği bir rotaya ihtiyacı vardır. Bu, sıradan uygulama kodudur, bir Apidog özelliği değildir. İmzayı doğrulayan ve olayı kaydeden minimal bir Express işleyicisi şöyle görünür:
import express from "express";
import Stripe from "stripe";
const app = express();
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY);
const endpointSecret = process.env.STRIPE_WEBHOOK_SECRET;
app.post(
"/webhooks/stripe",
express.raw({ type: "application/json" }),
async (req, res) => {
let event;
try {
event = stripe.webhooks.constructEvent(
req.body,
req.headers["stripe-signature"],
endpointSecret
);
} catch (err) {
return res.status(400).send(`Signature check failed: ${err.message}`);
}
// Persist the event so a test can read it back later.
await db.query(
`INSERT INTO stripe_event_logs (event_id, type, payload, handled_at)
VALUES ($1, $2, $3, now())
ON CONFLICT (event_id) DO NOTHING`,
[event.id, event.type, JSON.stringify(event.data.object)]
);
if (event.type === "payment_intent.succeeded") {
const intent = event.data.object;
await markOrderPaid(intent.metadata.order_id);
}
res.json({ received: true });
}
);
Burada iki şey önemlidir. Birincisi, herhangi bir şeye güvenmeden önce Stripe imzasını `constructEvent` ile doğrulamanız gerekir, ki bu, herhangi bir web kancası alıcısı için vazgeçilmez güvenlik adımıdır. Bu kontrolün ardındaki tüm gerekçeyi öğrenmek isterseniz, web kancası imza doğrulaması hakkındaki açıklamamız, ham-gövde karşılaştırmasının bunu yapmanın tek güvenli yolu olduğu konusuna girer. İkincisi, olayı bir `Stripe event logs` tablosuna yazarsınız. Bu satır Apidog'un okuyacağı şeydir. `ON CONFLICT DO NOTHING` maddesi, Stripe aynı olayı birden fazla kez teslim edebileceği için günlüğü değişmez kılar (idempotent yapar).
Adım 2: Apidog ortamında veritabanınızı bağlayın
Apidog, ilgili ortamda bir veritabanına bağlanmayı destekler ve bu bağlantı, tüm bu modelin çalışmasını sağlar. CI çalışmanızın hedeflediği ortam için (ister bir hazırlık (staging) Postgres'i ister özel bir test veritabanı olsun) bir veritabanı bağlantısı kurun. Bağlantı kurulduğunda, bir test adımı üzerinde SQL çalıştırabilir ve gerçek satırları geri alabilir.
Bağlantıyı test ettiğiniz ortama uygun hale getirin. Hazırlık ortamına karşı çalışan bir test, hazırlık veritabanını sorgulamalıdır, böylece testinizin tetiklediği olay, testinizin okuduğu olaydır. Eşleşmeyen ortamlar, başarılı bir yakalama uç noktasının doğrulamayı yine de geçememesinin en yaygın nedenidir.
Adım 3: Günlüğü sorgulamak için bir İstek Sonrası İşleyici (Post-Request Processor) ekleyin
İşin özü budur. `Post-Request Processor`, Apidog'un veritabanınızı sorgulayan ve bir test içinde kaydedilen web kancası olayını doğrulayan özelliğidir. Bunu test senaryonuzdaki bir isteğe eklersiniz. İstek çalıştıktan sonra, işlemci SQL'inizi yürütür, depolanan olayı okur ve sonucu doğrulamanıza olanak tanır.
`payment_intent.succeeded` durumu için gerçekçi bir akış:
- Test senaryonuz ödemeyi tetikler. Bu, Stripe test modunda bir ödeme amacı oluşturan ve bunu onaylayan bir istek veya yakalama uç noktanıza bilinen bir test olayı gönderen bir düzenek (fixture) olabilir.
- Stripe, web kancasını `/webhooks/stripe` rotanıza teslim eder, bu da imzayı doğrular ve `stripe_event_logs` tablosuna bir satır yazar.
- Bir sonraki adımdaki bir `Post-Request Processor` (İstek Sonrası İşleyici), o tabloyu olay için sorgular.
İşleyicinin çalıştırdığı sorgu düz SQL'dir:
SELECT event_id, type, payload, handled_at
FROM stripe_event_logs
WHERE type = 'payment_intent.succeeded'
ORDER BY handled_at DESC
LIMIT 1;
Ardından dönen satır üzerinde doğrulama yaparsınız. Kaydedilen veriler beklentilerinizle eşleştiğinde test başarılı olur: `type` `payment_intent.succeeded` olmalı, `event_id` tetiklediğinizle eşleşmeli, `payload` miktarı ücretlendirdiğinizle eşit olmalı ve `handled_at` alanı doldurulmuş olmalı; bu, işleyicinizin aslında çalıştığını, satırın bir yer tutucu olmadığını kanıtlar. Depolanan web kancası olayını alın, beklenen sonuçla karşılaştırın ve doğrulamanın geçip geçmediğine karar vermesini sağlayın.
Web kancası teslimatının zamanlaması anlık olmadığı için, sorgulamadan önce olayın gelmesi için bir an bekleyin. Kısa bir gecikme adımı veya başarısız olmadan önce sorguyu birkaç kez yeniden deneyen bir yoklama döngüsü, testin Stripe'ın teslimatıyla yarışmasını engeller. Web kancalarının eşzamansız doğasının test tasarımınıza sızdığı tek yer burasıdır ve küçük bir yeniden deneme penceresi bunu temiz bir şekilde halleder.
Yerel geliştirme sırasında gerçek zamanlı yönlendirme üzerine bir not
Yakala-sonra-sorgula modeli, bir veritabanı ve depolanmış bir kaydın tam olarak istediğiniz şey olduğu CI için tasarlanmıştır. Yerel geliştirme farklı bir durumdur. Dizüstü bilgisayarınızda işleyiciyi yazarken, Stripe `localhost`'a doğrudan ulaşamaz, bu nedenle olayları makinenize gerçek zamanlı olarak yönlendirecek bir şeye ihtiyacınız vardır.
Bunun için Apidog'un belgeleri, örnek olarak Stripe CLI ve Ngrok'u göstererek bir web kancası aktarım hizmetini işaret eder. Stripe CLI, olayları dinleyebilir ve doğrudan yerel bağlantı noktanıza iletebilir:
stripe listen --forward-to localhost:3000/webhooks/stripe
Bu size işleyiciyi oluştururken canlı olaylar sağlar. Ngrok, yerel bağlantı noktanızı Stripe uç noktası olarak kaydettiğiniz genel bir URL'de açarak aynı işi yapar. Bunları iç geliştirme döngüsü için kullanın, ardından işlem hattınızda çalışan doğrulamalar için veritabanı artı `Post-Request Processor` akışına güvenin. İkisi birbirini tamamlar: oluşturmak için aktarıcı, kanıtlamak için yakala-sonra-sorgula.
Bunu Apidog'un yerel Web Kancası (Webhook) özelliğiyle karıştırmayın
Apidog'un kelimenin tam anlamıyla `Webhook` olarak adlandırılan bir özelliği vardır ve Stripe olaylarını böyle yakaladığınızı varsaymak kolaydır. Bu doğru değildir ve bunları karıştırmak size bir öğleden sonraya mal olacaktır. Yerel `Webhook` özelliği, giden bir web kancasını tanımlamak ve belgelemek içindir; yani, bir olay meydana geldiğinde kendi sisteminizin çağırdığı bir HTTP uç noktasıdır. Sistem, harici bir URL'ye çağrıyı başlatır, ki bu müşterilerin sizi çağırdığı normal bir uç noktanın tersidir. Bu, API belgelerinizde durum değişikliği bildirimlerini ve eşzamansız görev sonuçlarını açıklamak için kullanılır, Stripe'ın gelen çağrılarını almak için değil.
Kendi giden web kancalarınızdan birini belgelemek isterseniz, akış kısadır:
- Sol kenar çubuğundaki `+` simgesine tıklayın.
- `Yeni Diğer Protokol API'leri`ni, ardından `Webhook`'u seçin.
- Gerekli alanları doldurun: `İstek Yöntemi` (genellikle POST), bir `Web Kancası Adı`, yalnızca test için isteğe bağlı bir `Hata Ayıklama URL'si` ve istek gövdesi, başlıklar ve yapılandırma için `Diğer Bilgiler`.
- `Kaydet`'e tıklayın.
Denemek için, `Hata Ayıklama URL` alanına bir URL girin ve web kancası çağrısını simüle etmek için `Gönder`'e tıklayın. Unutulmaması gereken bir uyarı: `Hata Ayıklama URL`'si yalnızca test amaçlıdır ve yayınlanmış belgelerinizde veya OpenAPI dışa aktarımınızda görünmeyecektir. Olay geri çağrımlarının (event callbacks) tasarlanması ve belgelenmesi hakkında daha kapsamlı bilgi için, API tasarımında web kancaları hakkındaki yazımız nereye uyduklarını kapsar. Bu makale için kısa versiyon: yerel `Webhook` özelliği giden olaylarınızı tanımlar ve yakala-sonra-sorgula modeli Stripe'ın gelen olaylarını doğrular. Bunları zihninizde ayrı kutularda tutun.
Varyasyonlar ve sağlamlaştırma
Temel doğrulama çalıştığında, birkaç iyileştirme onu üretim kalitesine getirir. İlk olarak, sadece olay türünden fazlasını doğrulayın. Tetiklediğiniz olayın, önceki bir çalıştırmadan kalan değil, doğruladığınız olay olduğundan emin olmak için `event_id`'yi baştan sona kontrol edin. Olaylar birikirse, her test çalıştırması için `stripe_event_logs` tablosunu boşaltın veya kapsamını belirleyin.
İkincisi, başarısızlık yollarını test edin. İşleyicinizin reddetmesi gereken bir olay (kötü bir imza veya beklenmedik bir tür) tetikleyin ve hiçbir `handled_at` zaman damgasının yazılmadığını doğrulayın. Sadece başarılı senaryoları kontrol eden bir web kancası test paketi, sizi sabah 2'de uyandıran durumları gözden kaçırır. Ödeme web kancası en iyi uygulamaları hakkındaki notlarımız, bu testlere kodlanmaya değer idemptotency ve yeniden deneme davranışını kapsar.
Üçüncüsü, doğrulamayı sadece teslimata değil, iş anlamına sıkı sıkıya bağlı tutun. “Olay ulaştı” ifadesi, “sipariş ödenmiş duruma geçti” ifadesinden daha zayıftır. İşleyiciniz bir `orders` tablosunu güncelliyorsa, alt akış durumunun değiştiğini doğrulayan ikinci bir sorgu ekleyin, böylece test sadece günlük yazmayı değil, tüm zinciri kanıtlar.
Bunu birleştirme kapısının ötesine de taşıyabilirsiniz. Senaryo Apidog'da kaydedildikten sonra, arızalı bir web kancası işleyicisinin dağıtımlar arasında bile ortaya çıkmasını sağlamak için belirli aralıklarla çalışacak şekilde zamanlayın. Apidog'da API testleri nasıl zamanlanır hakkındaki kılavuzumuz, aynı doğrulamayı bir zamanlayıcıya nasıl koyacağınızı gösterir.
Apidog CLI ile iş akışını otomatikleştirin
Yukarıdaki her şey gözetimsiz çalıştığında karşılığını verir ve işte burada Apidog CLI devreye girer. Bu, doğası gereği bir CI hikayesidir, bu nedenle kaydedilmiş senaryoyu işlem hattınıza bağlamak doğal bir sondur. CLI'ı yükleyin ve belirtecinizle (token) kimlik doğrulaması yapın:
npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>
Ardından, olay günlüklerini barındıran veritabanına sahip ortama karşı kaydedilmiş web kancası doğrulama senaryonuzu başsız (headless) olarak çalıştırın:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t <SCENARIO_ID> -e <ENV_ID> -r cli
Burada `-t` test senaryosu kimliğidir, `-e` ortam kimliğidir ve `-r` raporlayıcıyı seçer. CI yapıtlarınız için konsol çıktısının yanı sıra göz atılabilir bir rapor isterseniz `-r html,cli` kullanın. Senaryo, `Post-Request Processor`'ı ve veritabanı sorgusunu içerir, böylece tek bir komut akışı tetikler, `stripe_event_logs` satırını okur ve doğrulama başarısız olursa sıfır olmayan bir çıkış kodu döndürür, ki bu bir işlem hattının birleştirmeyi (merge) engellemesi için tam olarak ihtiyacı olan şeydir. Apidog CLI kurulum kılavuzu token kurulumunu kapsar ve CI/CD işlem hattı açıklamamız bu komut etrafındaki tam GitHub Actions bağlantısını gösterir.
Sıkça sorulan sorular
Apidog bir Stripe web kancasını doğrudan alabilir mi? Hayır. Apidog'un belgeleri açıkça “web kancalarını doğal olarak dinlemeyi desteklemez” der. Olayı kendi arka uç uç noktanızda yakalar, bir veritabanında saklarsınız ve Apidog bunu bir `Post-Request Processor` ile geri okur. Yerel geliştirme sırasında gerçek zamanlı yönlendirme için bunun yerine Stripe CLI veya Ngrok gibi bir aktarıcı kullanın.
Doğrulamalar aslında nerede gerçekleşir? Test senaryonuzdaki bir isteğin `Post-Request Processor` adımında. Ortamda yapılandırdığınız veritabanı bağlantısı üzerinden `Stripe event logs` tablonuzu sorgular, depolanan olayı alır ve beklenen değerlerinizle karşılaştırır. Kaydedilen veriler eşleştiğinde test başarılı olur.
Veritabanı doğrulama akışı için ücretli bir plana ihtiyacım var mı? Apidog'un bu iş akışı için olan belgeleri herhangi bir plan kısıtlaması belirtmez, bu yüzden bu kılavuz da böyle bir şey uydurmayacaktır. Dürüst cevap, fiyatlandırma sayfasındaki güncel plan ayrıntılarını kontrol etmektir. Apidog'u İndir'i tıklayabilir ve Post-Request Processor ile ortam veritabanı bağlantısını kendiniz görmek için bir test projesi kurabilirsiniz.
Tetikleme ve teslimat arasındaki gecikmeyi nasıl ele alırım? Web kancası teslimatı anlık değildir, bu nedenle testinizin Stripe ile yarışmaması için sorgudan önce kısa bir bekleme veya yoklama yeniden denemesi ekleyin. Birkaç saniye içinde birkaç yeniden deneme genellikle yeterlidir. Eşzamansız uç noktalarda doğrulama konusunda yeniyseniz, Stripe'a özgü detayları eklemeden önce genel web kancaları nasıl test edilir kılavuzundan başlayın.
Yerel Web Kancası özelliği burada hiç işe yarar mı? Stripe olaylarını yakalamak için değil. Bu özellik, kendi giden web kancalarınızı tanımlar ve belgeler, burada sisteminiz harici bir URL'yi çağırır. Bu, bu makalede kullanılan gelen yakala-sonra-sorgula modelinden ayrı bir belge ve tasarım aracıdır. İkisini açıkça ayrı tutun.
Özetliyor
Stripe'ı Apidog'a yönlendirip olayları canlı olarak yakalayamazsınız ve aksi gibi davranmak hayal kırıklığıyla dolu bir öğleden sonraya yol açar. Desteklenen yol ilk bakışta göründüğünden daha temizdir: web kancasını kendi uç noktanızda yakalayın, bir `Stripe event logs` tablosuna kaydedin, ardından Apidog'un `Post-Request Processor`'ının o kaydı sorgulamasını ve olayın işlendiğini doğrulamasını sağlayın. Kaydedilmiş senaryoyu `apidog run` içine alın ve işlem hattınız, her birleştirmede (merge) gerçek bir ödeme olayının siparişinizi ödenmiş duruma getirdiğini kanıtlar. Ücretsiz deneyin, kredi kartı gerekmez ve en önemli web kancasının arkasına gerçek bir doğrulama koyun.