DEV Community

Cover image for Webhook'lar Nasıl Test Edilir: Araçlar ve Adım Adım Kılavuz
Tobias Hoffmann
Tobias Hoffmann

Posted on • Originally published at apidog.com

Webhook'lar Nasıl Test Edilir: Araçlar ve Adım Adım Kılavuz

Bir web kancasını test etmek için sağlayıcıya erişilebilir bir URL verin, gerçek veya test bir olayı tetikleyin, ardından işleyicinizin yükü aldığını, imzayı doğruladığını ve beklenen yan etkiyi ürettiğini kontrol edin. Web kancalarında uygulamanız çağıran değil alıcı olduğu için test süreci; yakalama URL’si, yerel tünel, sağlayıcı tetikleyicisi ve tekrarlanabilir doğrulama adımlarından oluşur.

Apidog'u bugün deneyin

Web Kancalarını Normal API'lerden Daha Zor Test Etmenin Nedenleri

Normal bir API çağrısında isteği siz başlatırsınız: yöntemi seçer, gövdeyi gönderir ve yanıtı okursunuz. Web kancalarında akış tersine döner. Sağlayıcı, kendi zamanlamasıyla, kendi tanımladığı yükü sizin uç noktanıza gönderir.

Bu durum dört pratik test problemi yaratır:

  1. Olayı her zaman doğrudan tetikleyemezsiniz. Örneğin payment_intent.succeeded yalnızca Stripe tarafında ilgili test akışı çalıştığında oluşur.
  2. Teslimat asenkrondur. Testiniz bir dönüş değerini beklemek yerine gelen HTTP isteğini yakalamalıdır.
  3. Yük şeması sağlayıcıya aittir. İşleyiciniz GitHub, Stripe veya Slack’in gönderdiği gerçek alanları ayrıştırmalıdır.
  4. Çoğu sağlayıcı imza kullanır. Uç noktanız, gövdeyi işlemeden önce imza başlığını doğrulamalıdır. Bu adımı atlayan testler gerçek güvenlik hatalarını gizleyebilir.

İmza doğrulama detayları için web kancası imza doğrulama kılavuzuna bakabilirsiniz.

Web kancasının entegrasyonunuz için doğru model olup olmadığını değerlendiriyorsanız, web kancaları ve yoklama ile web kancası ve WebSocket karşılaştırmaları da faydalıdır.

Web Kancası Test Araç Seti

Uçtan uca bir web kancası testi için genellikle şu dört aracı birlikte kullanırsınız:

  • Ham yükleri görmek için yakalama hizmeti
  • Localhost’u dışarı açmak için tünel
  • Gerçek olay üretmek için sağlayıcı tetikleyicisi
  • Yanıtları ve yan etkileri doğrulamak için test aracı

1. Gerçek Yükü Yakalama

İşleyici kodunu yazmadan önce sağlayıcının gerçekten ne gönderdiğini görün. Bunun için sağlayıcı web kancası URL’sini geçici bir yakalama URL’siyle değiştirin.

Kullanabileceğiniz araçlar:

  • webhook.site: Sayfa açıldığında benzersiz bir URL üretir. Gelen isteğin yöntemini, başlıklarını ve gövdesini gösterir. Ücretsiz URL’ler 7 gün sonra sona erer, 100 istek ve 10 MB istek boyutu sınırı vardır.
  • Beeceptor: Ücretsiz HTTPS uç noktası sağlar. Gelen yükleri inceleyebilir ve aynı araçla mock endpoint oluşturabilirsiniz.
  • Pipedream RequestBin: Gelen HTTP isteklerini yakalamak için kullanılan başka bir pratik seçenektir.

Bu adımın amacı tek soruyu yanıtlamaktır:

Sağlayıcı gerçek ortamda nasıl bir payload gönderiyor?

Yakalanan örnek gövdeyi ve başlıkları daha sonra tekrarlanabilir testler için saklayın.

2. Localhost’u Tünel ile Açığa Çıkarma

Sağlayıcılar doğrudan localhost:3000 adresinize erişemez. Bu nedenle yerel sunucunuzu herkese açık bir HTTPS URL’si üzerinden erişilebilir hale getirmeniz gerekir.

ngrok ile 

brew install ngrok                          # macOS
ngrok config add-authtoken $YOUR_TOKEN
ngrok http 3000                             # public HTTPS URL -> localhost:3000
Enter fullscreen mode Exit fullscreen mode

ngrok ücretsiz hesaplarda otomatik bir geliştirme alan adı verir. Özel alan adları ücretli plan gerektirir.

cloudflared ile 

cloudflared tunnel --url http://localhost:3000
Enter fullscreen mode Exit fullscreen mode

Komutun ürettiği public URL’yi sağlayıcının web kancası ayarlarına ekleyin. Bundan sonra gelen olaylar yerel sunucunuza yönlendirilir.

Bu yaklaşımın daha ayrıntılı açıklaması için web kancası hizmetleriyle localhost API'lerini nasıl test edeceğinize bakabilirsiniz.

3. Sağlayıcıdan Test Olayı Tetikleme

Yakalama URL’si veya tünel ancak sağlayıcı bir şey gönderdiğinde işe yarar. Bu nedenle test olayını sağlayıcı tarafında tetiklemeniz gerekir.

Stripe CLI

Stripe CLI, sanal alan olaylarını yerel işleyicinize yönlendirebilir ve test için kullanılacak web kancası imza sırrını yazdırır.

# Tüm olayları yerel işleyiciye ilet
stripe listen --forward-to localhost:3000/webhooks

# Sadece belirli olayları ilet
stripe listen --events payment_intent.succeeded,checkout.session.completed \
  --forward-to localhost:3000/webhooks
Enter fullscreen mode Exit fullscreen mode

Dinleyici çalışırken test olayı üretin:

stripe trigger payment_intent.succeeded
stripe trigger checkout.session.completed
stripe trigger --help                       # desteklenen olayları listeler
Enter fullscreen mode Exit fullscreen mode

Not: stripe trigger desteklenen API nesneleri oluşturur ve yan etkiler üretebilir. Örneğin payment_intent.succeeded, ayrıca payment_intent.created olayını da yayabilir.

GitHub

GitHub, web kancası teslimatlarını kısa süreli olarak saklar ve tekrar göndermenize izin verir.

Adımlar:

  1. Depoya gidin.
  2. Settings sayfasını açın.
  3. Code and automation > Webhooks bölümüne gidin.
  4. Web kancası URL’sine tıklayın.
  5. Recent deliveries sekmesini açın.
  6. Bir delivery GUID seçin.
  7. Redeliver düğmesine tıklayın.

Kısıtlar:

  • Sadece son 3 gündeki teslimatlar yeniden gönderilebilir.
  • Depoda yönetici erişimi gerekir.
  • GitHub başarısız teslimatları otomatik yeniden göndermez; tekrar oynatma manueldir.

Slack

Slack gelen web kancaları için en basit test yöntemi doğrudan JSON POST etmektir.

curl -X POST https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX \
  -H 'Content-type: application/json' \
  -d '{"text":"Merhaba dünya."}'
Enter fullscreen mode Exit fullscreen mode

Slack web kancası URL’si gizli bilgi kabul edilmelidir. URL’yi istemci tarafı koda veya herkese açık depoya koymayın. Slack sızan URL’leri iptal edebilir.

4. İşleyiciyi Doğrulama

Yakalama ve tetikleme, bağlantının çalıştığını gösterir. Ancak işleyicinizin doğru davrandığını kanıtlamaz.

En basit doğrulama, temsilî bir payload ile uç noktaya POST atmaktır:

curl -X POST http://localhost:3000/webhooks \
  -H 'Content-Type: application/json' \
  -H 'Stripe-Signature: t=...,v1=...' \
  -d '{"id":"evt_test","type":"payment_intent.succeeded","data":{"object":{"id":"pi_123","status":"succeeded"}}}'
Enter fullscreen mode Exit fullscreen mode

Bu hızlı kontrol için yeterlidir. Ancak CI’da çalışacak, tekrar edilebilir ve onaylamalı testler için kaydedilmiş API istekleri ve senaryolar daha uygundur.

Apidog ile Web Kancalarını Test Etme

Apidog, API tasarlama, hata ayıklama, test etme, mock oluşturma ve dokümantasyon için kullanılan hepsi bir arada bir API platformudur. Özel bir “web kancası gelen kutusu” sunmaz; bu nedenle web kancası testlerinde en çok şu işler için kullanılır:

  • Yakalanmış payload’ları tekrar kullanılabilir istek olarak kaydetme
  • Yanıt durumunu ve gövdesini doğrulama
  • Hatalı payload ve imza senaryoları oluşturma
  • Sağlayıcı yerine mock sunucu kullanma
  • CI içinde senaryo çalıştırma

Örnek Payload’ı Kaydedilebilir İsteğe Dönüştürün

Önce webhook.site gibi bir araçtan yakaladığınız gerçek payload’ı alın.

Apidog’da:

  1. Yeni bir istek oluşturun.
  2. Method olarak POST seçin.
  3. URL olarak işleyicinizin adresini girin.
  4. JSON gövdesine yakalanan payload’ı yapıştırın.
  5. Sağlayıcının gönderdiği başlıkları ekleyin.
  6. İşleyiciniz kontrol ediyorsa imza başlığını da ekleyin.

Örneğin:

POST http://localhost:3000/webhooks
Content-Type: application/json
Stripe-Signature: t=...,v1=...
Enter fullscreen mode Exit fullscreen mode

Bu isteği kaydettiğinizde aynı payload’ı tekrar tekrar gönderebilir, varyasyonlarını oluşturabilir ve test senaryolarına ekleyebilirsiniz.

Pratik olarak şu varyasyonları kaydetmek faydalıdır:

  • Geçerli payload + geçerli imza
  • Geçerli payload + bozuk imza
  • Eksik zorunlu alan
  • Bilinmeyen event type
  • Aynı event ID ile tekrar gönderim

Görsel Onay Oluşturucu ile Yanıtı Doğrulayın

Payload göndermek testin yalnızca ilk yarısıdır. İkinci yarı, işleyicinin doğru yanıtı verdiğini doğrulamaktır.

Apidog’da:

  1. İsteği veya senaryo adımını açın.
  2. Post Processors / Son İşleyiciler bölümüne gidin.
  3. + Ekle seçeneğine tıklayın.
  4. Assertion / Onaylama seçin.
  5. Yanıt gövdesi veya durum kodu için kural ekleyin.

Örneğin JSON yanıtında durum alanını kontrol etmek için:

JSONPath: $.data.status
Condition: Equals
Expected: succeeded
Enter fullscreen mode Exit fullscreen mode

JSON kökü için $ kullanabilirsiniz.

Bu sayede testiniz sadece “200 döndü” demek yerine şunu doğrular:

  • HTTP durum kodu doğru mu?
  • Yanıt gövdesindeki durum beklenen değer mi?
  • Sipariş veya ödeme kimliği doğru mu?
  • Hata senaryosunda doğru hata mesajı dönüyor mu?

Görsel onaylamalar değerleri dize olarak karşılaştırır. Tür hassasiyetli kontroller gerekiyorsa, örneğin gerçek sayı veya boolean doğrulaması, Postman uyumlu pm.test sözdizimiyle özel betik kullanabilirsiniz.

Sağlayıcı Yerine Mock Sunucu Kullanın

Bazı testlerde uygulamanızın bir sağlayıcıyı çağırdığı yönü doğrulamak istersiniz. Yerel veya CI testlerinde gerçek sağlayıcıya istek atmak istemeyebilirsiniz. Bu durumda mock sunucu kullanabilirsiniz.

Apidog üç tür mock sunucu sağlar:

  • Local Mock: Masaüstü istemcisiyle çalışır. Sadece istemci açıkken erişilebilir.
  • Cloud Mock: Apidog sunucularında barındırılır. 7/24 çalışabilir ve açılıp kapatılabilir. Varsayılan olarak kapalıdır.
  • Runner Mock: Kendi barındırdığınız runner altyapısında çalışır ve ekibinizle paylaşılır.

Her HTTP endpoint için bir Mock modülü bulunur. Mock URL’sini:

  • Design modundaki API sekmesinden
  • Debug modundaki Mock sekmesinden

kopyalayabilirsiniz.

Dikkat: Sadece / ile başlayan yollar mock ortamına yönlendirilir.

Test sırasında uygulama konfigürasyonunda gerçek sağlayıcı URL’si yerine mock URL kullanın. Böylece entegrasyonunuz gerçek API çağrısı yapmadan öngörülebilir yanıtlar alır.

Apidog CLI ile CI’da Web Kancası Testleri Çalıştırma

Senaryonuz yerelde geçtikten sonra Apidog CLI ile CI pipeline’a ekleyebilirsiniz. Apidog CLI, Node.js v16 veya sonrası gerektirir.

Kurulum:

npm install -g apidog-cli
node -v && apidog -v && which node && which npm && which apidog
Enter fullscreen mode Exit fullscreen mode

Kaydedilmiş bir senaryoyu çevrimiçi çalıştırmak için CI/CD bölümündeki komut satırı parametrelerini kullanın:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 637132 -e 358171 -d 3497013 -r html,cli
Enter fullscreen mode Exit fullscreen mode

Parametreler:

  • -t: Test senaryosu
  • -e: Ortam, zorunludur
  • -d: Test verisi; CSV/JSON dosya yolu veya kayıtlı veri kümesi ID’si olabilir
  • -r: Rapor formatı; cli, html, json, junit değerlerini kabul eder

Daha ayrıntılı kullanım için Apidog CLI eğitimine bakabilirsiniz.

Kendi web kancası testlerinizi görsel olarak oluşturmak ve doğrulamak isterseniz Apidog'u ücretsiz deneyin, kredi kartı gerekmez.

Adım Adım Web Kancası Test İş Akışı

Aşağıdaki sıra, çoğu web kancası entegrasyonu için uygulanabilir bir test akışıdır.

1. Gerçek payload’ı yakalayın

Sağlayıcı web kancası URL’sini geçici olarak webhook.site gibi bir yakalama URL’sine yönlendirin.

Kontrol edin:

  • HTTP method
  • Başlıklar
  • Gövde yapısı
  • Event type alanı
  • İmza başlığı
  • Tekrar gönderimde değişen alanlar

2. İşleyicinizi yerelde çalıştırın

Uygulamanızı başlatın:

npm run dev
Enter fullscreen mode Exit fullscreen mode

veya kullandığınız framework’e göre ilgili komutu çalıştırın.

Örnek endpoint:

http://localhost:3000/webhooks
Enter fullscreen mode Exit fullscreen mode

3. Localhost’u public URL’ye açın

ngrok:

ngrok http 3000
Enter fullscreen mode Exit fullscreen mode

veya cloudflared:

cloudflared tunnel --url http://localhost:3000
Enter fullscreen mode Exit fullscreen mode

Üretilen HTTPS URL’yi sağlayıcının web kancası ayarlarına ekleyin.

4. Gerçek test olayı tetikleyin

Sağlayıcıya göre:

stripe trigger payment_intent.succeeded
Enter fullscreen mode Exit fullscreen mode

veya GitHub’da Redeliver düğmesini kullanın.

Slack için:

curl -X POST $SLACK_WEBHOOK_URL \
  -H 'Content-type: application/json' \
  -d '{"text":"Test mesajı"}'
Enter fullscreen mode Exit fullscreen mode

5. İmza doğrulamayı test edin

Aynı payload’ı iki şekilde gönderin:

  • Geçerli imzayla
  • Bozuk veya eksik imzayla

Beklenen sonuç:

  • Geçerli imza kabul edilir.
  • Geçersiz imza reddedilir.

Örnek HTTP durumları:

200 OK        # geçerli imza
400/401/403   # geçersiz imza
Enter fullscreen mode Exit fullscreen mode

6. Yanıtı ve yan etkileri doğrulayın

Apidog’da kaydedilmiş isteğe assertion ekleyin.

Kontrol edilebilecek şeyler:

  • HTTP status 200, 202 veya beklenen değer mi?
  • Yanıt gövdesi beklenen alanları içeriyor mu?
  • Veritabanında kayıt oluştu mu?
  • Aynı event tekrar gelirse idempotent davranıyor mu?
  • Aşağı akış servise beklenen çağrı yapıldı mı?

7. Otomatikleştirin

Senaryoyu Apidog CLI ile CI’a taşıyın. Böylece her pull request veya push işleminde web kancası işleyiciniz tekrar test edilir.

Web kancası sistemini tüketmek yerine tasarlıyorsanız, güvenilir web kancaları nasıl tasarlanır ve ödeme web kancası en iyi uygulamaları yazıları yeniden deneme, idempotency ve güvenlik konularını kapsar.

Daha geniş bağlam için web kancaları API kılavuzu ve web kancaları ve olay odaklı mimari yazılarına bakabilirsiniz.

Sıkça Sorulan Sorular

Bir web kancasını nasıl test edersiniz?

Sağlayıcıya erişilebilir bir URL verin, gerçek veya test olayını tetikleyin, ardından işleyicinizin payload’ı aldığını, imzayı doğruladığını, doğru HTTP durumunu döndürdüğünü ve beklenen yan etkiyi oluşturduğunu kontrol edin. Önce gerçek payload’ı yakalayın, sonra aynı payload ile tekrarlanabilir bir test isteği oluşturun.

Web kancalarını yerel olarak nasıl test edersiniz?

İşleyicinizi yerel bir portta çalıştırın ve public HTTPS URL üretmek için tünel kullanın:

ngrok http 3000
Enter fullscreen mode Exit fullscreen mode

veya:

cloudflared tunnel --url http://localhost:3000
Enter fullscreen mode Exit fullscreen mode

Public URL’yi sağlayıcının web kancası ayarlarına yapıştırın ve test olayı tetikleyin. Gelen istekler yerel sunucunuza düşer; breakpoint koyup canlı olarak inceleyebilirsiniz.

Postman ile bir web kancasını nasıl test edersiniz?

Postman, oluşturulmuş payload’ı web kancası endpoint’inize POST edebilir ve yanıtı doğrulayabilir. Ancak tek başına gerçek gelen web kancasını yakalamaz. Aynı durum Apidog için de geçerlidir: sağlayıcının payload’ı ve başlıklarıyla bir istek oluşturur, assertion eklersiniz ve bunu tekrar kullanılabilir test olarak kaydedersiniz. Gerçek gelen olayı görmek için yakalama hizmeti veya tünel kullanmanız gerekir.

Stripe web kancalarını nasıl test edersiniz?

Stripe CLI kullanın:

stripe listen --forward-to localhost:3000/webhooks
Enter fullscreen mode Exit fullscreen mode

Bu komut sanal alan olaylarını işleyicinize yönlendirir ve imza sırrı üretir. Ardından test olayı tetikleyin:

stripe trigger payment_intent.succeeded
Enter fullscreen mode Exit fullscreen mode

Desteklenen olayları görmek için:

stripe trigger --help
Enter fullscreen mode Exit fullscreen mode

Bazı tetiklemeler ek olaylar da üretebilir. Örneğin payment_intent.succeeded, payment_intent.created olayını da yayabilir.

Bir Slack web kancasını nasıl test edersiniz?

Slack gelen web kancası URL’sine JSON POST edin:

curl -X POST $SLACK_WEBHOOK_URL \
  -H 'Content-type: application/json' \
  -d '{"text":"Merhaba dünya."}'
Enter fullscreen mode Exit fullscreen mode

Başarılı test, yapılandırılmış Slack kanalına mesaj gönderir. Web kancası URL’sini gizli tutun; istemci tarafı koda veya herkese açık depoya koymayın.

Bir web kancası URL’sini nasıl test edersiniz?

URL’ye temsilî bir POST gönderin ve başarılı durum kodu ile beklenen davranışı doğrulayın. Hızlı kontrol için curl yeterlidir. Daha güvenilir test için gerçek payload’ı yakalayın, geçerli ve geçersiz imzalarla tekrar gönderin, ardından sadece 200 OK durumunu değil yanıt gövdesini ve yan etkileri de doğrulayın.

Top comments (0)