Apidog ile CI'da Stripe Webhook'larını Yakalama ve Doğrulama

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 bozulabilir: Web kancası gelir, işleyiciniz hata fırlatır ve bir destek bileti “Ödedim ama hesabım hâlâ ödenmemiş görünüyor” diyene kadar kimse fark etmez. Her dağıtımda olayın geldiğini ve doğru işlendiğini kanıtlayan bir CI testi istersiniz. Zorluk şudur: Web kancası, Stripe'ın size yaptığı bir HTTP çağrısıdır; sizin gönderdiğiniz bir istek değildir. Çoğu API test aracı istek gönderip yanıtı denetlemek için tasarlanmıştır. Bu kılavuz, bunu Apidog ile desteklenen bir yaklaşımla nasıl yapacağınızı gösterir. Daha geniş bağlam için web kancaları nasıl test edilir kılavuzuna ve Stripe'ın web kancası belgelerine bakabilirsiniz.

Apidog'u bugün deneyin

Çevresinde tasarım yapmanız gereken kısıtlama

Apidog'un kendi belgelerinde açıkça belirtilen temel gerçek şudur: “ApiDog doğal olarak web kancalarını dinlemeyi desteklemez.”

Yani Apidog, genel bir URL üzerinde Stripe'ın gelen çağrılarını gerçek zamanlı olarak yakalayan bir dinleyici değildir. Stripe'ı Apidog'a yönlendirip olayların akışını canlı izlemeyi beklemeyin.

Bunun yerine testinizi şu modelle kurun:

1. Web kancasını kendi arka ucunuzda yakalayın.
2. Olayı veritabanına kaydedin.
3. Apidog ile bu kaydı sorgulayın.
4. Beklenen iş sonucunu doğrulayın.

Bu “önce yakala, sonra doğrula” yaklaşımı CI için uygundur; çünkü veritabanı sorguları deterministik ve tekrarlanabilirdir.

Yakala-sonra-sorgula modeli

Bu model dört parçadan oluşur:

1. Gelen Stripe web kancalarını almak için arka uç hizmetinizde bir uç nokta oluşturun.
2. Olay verisini veritabanınızdaki stripe_event_logs tablosunda saklayın.
3. Veritabanını sorgulamak için Apidog Post-Request Processor kullanın.
4. Kaydedilen olayı ve iş sonucunu doğrulayın.

İlk iki adım uygulamanızda çalışır. Son iki adım ise Apidog test senaryosunda çalışır.

Adım 1: Yakalama uç noktasını oluşturun

Stripe'ın POST isteği gönderebileceği bir rota oluşturun. Aşağıdaki Express örneği Stripe imzasını doğrular, olayı kaydeder ve ödeme başarılıysa siparişi günceller:

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}`);
    }

    // Testin daha sonra okuyabilmesi için olayı kaydedin.
    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 kritik nokta vardır:

• Stripe imzasını constructEvent ile doğrulamadan hiçbir veriye güvenmeyin. Bu, web kancası alıcıları için temel güvenlik adımıdır. Ayrıntılar için web kancası imza doğrulaması yazısına bakabilirsiniz.
• Olayı stripe_event_logs tablosuna yazın. Apidog bu kaydı okuyarak doğrulama yapar.

ON CONFLICT (event_id) DO NOTHING bölümü önemlidir. Stripe aynı olayı birden fazla kez teslim edebilir; bu ifade günlük kaydını idempotent hâle getirir.

Adım 2: Apidog ortamında veritabanınızı bağlayın

Apidog'da test senaryonuzun çalışacağı ortam için veritabanı bağlantısı yapılandırın.

Örneğin:

• Staging API'yi test ediyorsanız staging Postgres veritabanını bağlayın.
• İzole bir CI ortamı kullanıyorsanız test veritabanını bağlayın.

Test edilen uygulama ile sorgulanan veritabanı aynı ortama ait olmalıdır. Aksi durumda web kancası doğru uç noktaya ulaşsa bile Apidog farklı veritabanını sorguladığı için test başarısız olur.

Adım 3: Olay günlüğünü sorgulamak için Post-Request Processor ekleyin

Post-Request Processor, bir istek tamamlandıktan sonra SQL çalıştırarak veritabanınızdaki kaydı doğrulamanızı sağlar.

payment_intent.succeeded için örnek test akışı:

1. Test senaryosu bir ödemeyi tetikler.
2. Stripe web kancasını /webhooks/stripe adresine teslim eder.
3. Uygulama imzayı doğrular ve stripe_event_logs tablosuna kayıt ekler.
4. Sonraki test adımındaki Post-Request Processor, ilgili kaydı sorgular.
5. Test, olayın ve sipariş durumunun doğru olduğunu doğrular.

Örnek SQL sorgusu:

SELECT event_id, type, payload, handled_at
FROM stripe_event_logs
WHERE type = 'payment_intent.succeeded'
ORDER BY handled_at DESC
LIMIT 1;

En az şu alanları doğrulayın:

• type değeri payment_intent.succeeded olmalı.
• event_id, testin tetiklediği Stripe olayıyla eşleşmeli.
• payload içindeki tutar, oluşturduğunuz ödeme tutarıyla eşleşmeli.
• handled_at dolu olmalı.
• Sipariş kaydı paid veya uygulamanızdaki eşdeğer ödeme durumuna geçmiş olmalı.

Sadece “olay ulaştı” kontrolü yeterli değildir. Asıl amaç, olayın iş mantığınızı gerçekten tetiklediğini kanıtlamaktır.

Teslimat gecikmesini yönetin

Web kancası teslimatı eşzamansızdır. Testiniz sorguyu çok erken çalıştırırsa Stripe teslimatı henüz tamamlanmamış olabilir.

Bunu önlemek için iki seçenek kullanın:

• Sorgudan önce kısa bir bekleme adımı ekleyin.
• Kısa süreli bir yoklama döngüsüyle sorguyu birkaç kez yeniden deneyin.

Örnek yeniden deneme mantığı:

5 kez dene
Her denemede:
  stripe_event_logs içinde event_id kaydını ara
  Kayıt bulunduysa doğrula ve testi bitir
  Bulunamadıysa 2 saniye bekle

Böylece testiniz Stripe teslimatıyla yarışmaz.

Yerel geliştirmede gerçek zamanlı yönlendirme

Yakala-sonra-sorgula modeli CI için uygundur. Yerel geliştirmede ise Stripe, doğrudan localhost adresinize erişemez.

Bu durumda bir web kancası aktarıcısı kullanın. Stripe CLI, olayları dinleyip yerel sunucunuza iletebilir:

stripe listen --forward-to localhost:3000/webhooks/stripe

Ngrok da yerel portunuzu genel bir URL üzerinden erişilebilir yaparak benzer şekilde çalışır.

Kısa kural:

• Yerelde geliştirme yaparken: Stripe CLI veya Ngrok kullanın.
• CI içinde doğrulama yaparken: Veritabanı + Post-Request Processor kullanın.

Bunu Apidog'un yerel Webhook özelliğiyle karıştırmayın

Apidog'da Webhook adlı bir özellik bulunur. Ancak bu özellik Stripe'ın gelen olaylarını yakalamak için değildir.

Yerel Webhook özelliği, sisteminizin başka bir servise gönderdiği giden web kancalarını tanımlamak ve belgelemek içindir. Örneğin, sisteminizde bir işlem tamamlandığında müşterinizin URL'sine POST isteği göndermeniz gibi.

Kendi giden web kancanızı belgelemek için:

1. Sol kenar çubuğundaki + simgesine tıklayın.
2. Yeni Diğer Protokol API'leri seçeneğini açın.
3. Webhook seçeneğini seçin.
4. İstek Yöntemi, Web Kancası Adı, isteğe bağlı Hata Ayıklama URL'si ve istek gövdesi bilgilerini girin.
5. Kaydet seçeneğine tıklayın.

Hata Ayıklama URL alanına bir URL girip Gönder seçeneğini kullanarak çağrıyı simüle edebilirsiniz. Bu URL yalnızca test içindir; yayınlanan belgelerde veya OpenAPI dışa aktarımında görünmez.

Daha fazla bilgi için API tasarımında web kancaları yazısına bakabilirsiniz.

Özetle:

• Apidog Webhook özelliği: Sizin gönderdiğiniz olayları belgelendirir.
• Yakala-sonra-sorgula modeli: Stripe'ın size gönderdiği olayları doğrular.

Sağlamlaştırma önerileri

Temel test çalıştıktan sonra aşağıdaki kontrolleri ekleyin.

1. event_id değerini uçtan uca doğrulayın

Yalnızca olay türünü kontrol etmeyin. Önceki bir test çalıştırmasından kalan kaydı yanlışlıkla doğrulamamak için Stripe event_id değerini test boyunca taşıyın.

İki yaklaşım kullanabilirsiniz:

• Her testten önce stripe_event_logs tablosunu temizlemek.
• Her test çalıştırmasına benzersiz bir order_id veya test etiketi eklemek.

2. Hata senaryolarını test edin

Sadece başarılı ödeme akışını test etmeyin.

Örneğin:

• Geçersiz imzalı istek gönderin.
• Beklenmeyen bir olay türü gönderin.
• Aynı event_id ile olayı tekrar gönderin.

Ardından şunları doğrulayın:

• Geçersiz imzalı olay işlenmemeli.
• Sipariş durumu değişmemeli.
• Yinelenen olay ikinci kez iş mantığını çalıştırmamalı.

Ödeme web kancası en iyi uygulamaları idempotency ve yeniden deneme davranışları için ek bağlam sağlar.

3. İş sonucunu da sorgulayın

Olay günlüğü tek başına yeterli değildir. Sipariş tablonuzu da doğrulayın.

Örnek:

SELECT id, payment_status, paid_at
FROM orders
WHERE id = $1;

Beklenen değerler:

payment_status = 'paid'
paid_at IS NOT NULL

Bu ikinci sorgu, testin yalnızca olayın kaydedildiğini değil, ödeme işleminin tamamlandığını da kanıtlamasını sağlar.

4. Senaryoyu zamanlanmış olarak çalıştırın

Senaryonuzu yalnızca merge sırasında değil, belirli aralıklarla da çalıştırabilirsiniz. Böylece dağıtımlar arasında bozulan bir web kancası işleyicisini tespit etme şansınız artar.

Bu yapılandırma için Apidog'da API testleri nasıl zamanlanır kılavuzuna bakabilirsiniz.

Apidog CLI ile iş akışını otomatikleştirin

Senaryonuz gözetimsiz çalıştığında CI işlem hattına ekleyin.

Önce Apidog CLI'ı yükleyin ve erişim belirteciyle kimlik doğrulaması yapın:

npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>

Ardından web kancası doğrulama senaryosunu ilgili ortamda çalıştırın:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t <SCENARIO_ID> -e <ENV_ID> -r cli

Parametreler:

• -t: Test senaryosu kimliği
• -e: Ortam kimliği
• -r: Raporlayıcı türü

CI yapıtlarında HTML raporu da istiyorsanız:

apidog run \
  --access-token $APIDOG_ACCESS_TOKEN \
  -t <SCENARIO_ID> \
  -e <ENV_ID> \
  -r html,cli

Senaryonuz Post-Request Processor ve veritabanı sorgularını içerdiği için bu tek komut:

1. Ödeme akışını tetikler.
2. Stripe olayını bekler.
3. stripe_event_logs kaydını okur.
4. Sipariş durumunu doğrular.
5. Başarısızlıkta sıfır olmayan çıkış koduyla CI işini başarısız yapar.

Kurulum için Apidog CLI kurulum kılavuzu, GitHub Actions örneği için ise CI/CD işlem hattı açıklamasına bakabilirsiniz.

Sıkça sorulan sorular

Apidog bir Stripe web kancasını doğrudan alabilir mi?

Hayır. Apidog belgelerine göre web kancalarını doğal olarak dinlemez. Olayı kendi arka uç uç noktanızda yakalayın, veritabanına kaydedin ve Apidog Post-Request Processor ile bu kaydı okuyup doğrulayın.

Yerel geliştirmede gerçek zamanlı yönlendirme için Stripe CLI veya Ngrok kullanın.

Doğrulamalar nerede gerçekleşir?

Test senaryonuzdaki Post-Request Processor adımında gerçekleşir. Bu adım, Apidog ortamında yapılandırılmış veritabanı bağlantısını kullanarak stripe_event_logs tablosunu sorgular ve sonuçları beklenen değerlerle karşılaştırır.

Veritabanı doğrulama akışı için ücretli plan gerekir mi?

Bu iş akışıyla ilgili Apidog belgeleri belirli bir plan kısıtlaması belirtmez. En güncel ayrıntılar için fiyatlandırma bilgilerini kontrol edin. Apidog'u İndir bağlantısını kullanarak test projesi oluşturabilir, ortam veritabanı bağlantısını ve Post-Request Processor akışını inceleyebilirsiniz.

Tetikleme ile teslimat arasındaki gecikmeyi nasıl yönetirim?

Sorgudan önce kısa bir bekleme ekleyin veya birkaç saniyelik yeniden deneme/yoklama mekanizması kullanın. Bu, testinizin Stripe teslimatı tamamlanmadan başarısız olmasını engeller.

Genel test yaklaşımı için web kancaları nasıl test edilir kılavuzuna bakabilirsiniz.

Yerel Webhook özelliği burada işe yarar mı?

Stripe olaylarını yakalamak için hayır. Bu özellik kendi sisteminizin gönderdiği giden web kancalarını tanımlamak ve belgelemek içindir. Stripe gibi harici sistemlerden gelen olayları doğrulamak için yakala-sonra-sorgula modelini kullanın.

Özet

Stripe'ı Apidog'a yönlendirip olayları canlı olarak yakalayamazsınız. Desteklenen ve CI dostu yaklaşım şudur:

1. Stripe web kancasını kendi uç noktanızda yakalayın.
2. İmzayı doğrulayın.
3. Olayı stripe_event_logs tablosuna kaydedin.
4. Sipariş durumunu güncelleyin.
5. Apidog Post-Request Processor ile olay kaydını ve iş sonucunu sorgulayın.
6. Senaryoyu apidog run ile CI işlem hattında çalıştırın.

Böylece her merge işleminde gerçek bir ödeme olayının siparişi beklenen şekilde ödenmiş duruma getirdiğini doğrulayabilirsiniz.