Webhook Delivery ve Güvenlik
Webhook kayıt, event filtreleme, imza doğrulama ve retry stratejisi.
Webhook’lar, ödeme sonucunu sizin sunucunuza güvenilir ve tekrarlanabilir şekilde taşımak içindir. Redirect veya confirm yanıtı kullanıcı deneyimini yönlendirir; siparişi kapatma kararı webhook veya sunucu tarafı payment sorgusu ile verilmelidir.
Yapılandırma
Her endpoint için tipik alanlar:
- HTTPS URL
- Dinlenecek event tipleri
- İmza doğrulama secret’ı
secret göndermezseniz platform bir anahtar üretebilir; canlıda secret’ı sizin yönetmeniz ve periyodik rotasyon önerilir. Sadece ihtiyacınız olan event’leri açın; gürültü ve yanlış işlem riskini azaltır.
Ödeme event ailesi (örnek)
Merchant tarafında sık görülen tipler:
| Event | Ne zaman düşünülür? |
|---|---|
payment.succeeded | Tahsilat tamamlandı |
payment.authorized | Auth-only başarı (auto_capture: false) |
payment.requires_action | 3DS veya ek kullanıcı adımı |
payment.requires_payment_method | Yöntem eksik veya son deneme başarısız |
payment.canceled / payment.refunded | İptal veya iade |
payment.processing | Ara durum (varsa) |
Charge tarafında charge.declined, charge.captured gibi event’ler operasyonel detay için kullanılabilir. Handler’da payment ID ile eşleştirin.
Delivery yaşam döngüsü
Bir teslimat kaydı kabaca şu durumlardan geçer:
| Status | Anlam |
|---|---|
PENDING | Kuyruğa alındı, henüz deneme yok |
PROCESSING | Endpoint’e gönderiliyor |
SUCCEEDED | 2xx alındı |
FAILED | Denemeler tükendi veya kalıcı hata |
Her başarısız deneme için ayrı attempt kaydı tutulur; next_retry_at ile yeniden deneme penceresi görülebilir.
Retry ve dayanıklılık
- Ağ kesintisi ve seçili HTTP hatalarında yeniden deneme yapılır.
- Bekleme süreleri kademeli artar.
- Üst sınır sonrası delivery
FAILEDolur; alarm ve manuel inceleme planlayın.
Merchant handler idempotent olmalı: aynı event veya payment ID ikinci kez gelse bile çift tahsilat veya çift sipariş kapatma olmamalı.
Güvenlik kontrol listesi
- Endpoint yalnızca HTTPS.
- Gelen imza doğrulanmadan state güncellenmez.
- PAN, CVV, provider secret veya ham challenge HTML loglanmaz.
- 2xx yanıt yalnızca iş mantığı başarıyla tamamlandıktan sonra döner.
Önerilen handler akışı
- İmzayı doğrula.
- Event ID veya payment ID ile daha önce işlendi mi bak.
- Domain state’i güncelle (sipariş, abonelik, fatura).
- 2xx dön.
Hesap sınırı
Webhook ayarları hesap bazlıdır. Çok hesaplı yapılarda endpoint’in doğru hesaba bağlı olduğunu operasyon checklist’inde doğrulayın.