Webhook'larla Sistemleri Birbirine Bağlamak

Entegrasyon dünyasında iki temel yaklaşım var: ya sistemlere sürekli "bir şey var mı?" diye sorarsın (polling), ya da onlar sana "bir şey oldu!" diye haber verir (webhook). İkincisi hem daha zarif hem de çok daha verimli. Bugün webhook'ların ne olduğunu, nasıl çalıştığını ve production ortamında kullanırken dikkat etmen gereken kritik noktaları ele alacağım.

Webhook Nedir?

En sade tanımıyla webhook, bir olay gerçekleştiğinde bir sistemin başka bir sisteme HTTP isteği göndermesidir. Örneğin bir e-ticaret platformunda ödeme tamamlandığında, ödeme sağlayıcısı senin belirlediğin bir URL'ye POST isteği atar. Bu istek içinde olayın tüm detayları — sipariş numarası, tutar, müşteri bilgisi — JSON formatında gelir.

Polling'e kıyasla avantajı açık: gereksiz istek yok, anlık tepki var, sunucu kaynakları boşa harcanmıyor.

Temel Çalışma Akışı

Bir webhook entegrasyonunun iskeletini şu adımlar oluşturur:

1. Endpoint tanımlama: Karşı sistemin istek atacağı bir URL hazırlarsın. Örneğin https://api.seninsistem.com/webhooks/odeme 2. Kayıt: Bu URL'yi ilgili platforma (Stripe, GitHub, Shopify vb.) tanımlarsın. 3. Olay tetiklenir: Karşı sistemde bir şey olur — ödeme, push, sipariş gibi. 4. İstek gelir: Platform senin endpoint'ine POST atar, sen de bunu işlersin. 5. 200 dönersin: Başarıyla aldığını belirtmek için HTTP 200 yanıtı gönderirsin. Aksi halde platform genellikle yeniden dener.

Production'da Dikkat Edilmesi Gerekenler

Webhook'lar basit görünse de production'da birkaç kritik nokta seni bekliyor:

🔐 İmza Doğrulaması (Signature Verification)

Gelen her isteğin gerçekten beklediğin sistemden geldiğini doğrulamalısın. Çoğu platform, isteği bir gizli anahtarla imzalar ve bu imzayı header'a ekler. Sen de aynı hesaplamayı yaparak eşleşip eşleşmediğini kontrol edersin. Bu adımı atlamak ciddi bir güvenlik açığıdır.

⚡ Hızlı Yanıt, Asenkron İşlem

Webhook handler'ın mümkün olduğunca hızlı 200 dönmeli; uzun süren işlemleri arka plana (queue, worker) atmalısın. Aksi halde timeout yaşarsın ve platform aynı olayı tekrar tekrar gönderir.

🔁 Idempotency (Tekrar Gelebilirlik)

Platform, yanıt alamadığını düşünüp aynı isteği birden fazla kez gönderebilir. İşlemlerini idempotent tasarla: aynı olay ikinci kez geldiğinde iki kez para çekme, iki kez kayıt oluşturma.

📋 Loglama ve Gözlemlenebilirlik

Her gelen webhook'u logla. Hangi olay geldi, ne zaman, nasıl işlendi? Bir sorun çıktığında bu loglar hayat kurtarır. Geliştirme ortamında ngrok gibi araçlarla webhook'ları local'e yönlendirerek debug edebilirsin.

🔄 Retry Mekanizması

Karşı sistem her zaman ayakta olmayabilir. Kendi gönderdiğin webhook'lar varsa, başarısız istekler için exponential backoff ile retry mekanizması kurman gerekir.

Gerçek Dünya Kullanım Senaryoları

• CI/CD: GitHub'a push yapılınca pipeline tetiklenir.
• Ödeme sistemleri: Stripe ödeme onayını anında bildirir.
• İzleme: Uptime monitörü kesinti olduğunda Slack'e mesaj atar.
• E-ticaret: Kargo firması teslimat güncellemesini sisteme iletir.

Sonuç

Webhook'lar, modern yazılım mimarisinin olmazsa olmazlarından biri. Doğru tasarlandığında sistemleri gevşek bağlı ama gerçek zamanlı bir şekilde birbirine bağlar. İmza doğrulaması, asenkron işleme ve idempotency üçlüsünü aklından çıkarmadığın sürece sağlam ve güvenilir bir entegrasyon kurabilirsin.

Bir sonraki yazıda event-driven mimarilerde webhook'ların message queue'larla nasıl bir arada kullanıldığına bakacağız.