Yeniden Deneme Politikası

Payven webhook teslimini at-least-once garantili çalıştırır. İlk denemede başarısız olursa belirli aralıklarla yeniden dener.

Yeniden deneme programı

Bir webhook için varsayılan max_retry_count: 5. Denemeler arası süreler:

Deneme	Yaklaşık bekleme süresi
1	Hemen
2	1 dakika sonra
3	5 dakika sonra
4	30 dakika sonra
5	2 saat sonra
6	24 saat sonra

5 başarısız denemeden sonra teslim kalıcı olarak başarısız kabul edilir ve daha fazla otomatik deneme yapılmaz. Konsoldan manuel replay tetiklenebilir.

Bekleme sürelerine ±%20 jitter uygulanır — eşzamanlı tetiklenen bin webhook’un retry’leri sabit aralıklarla çakışmaz, pencereye yayılır.

Hangi durumlarda retry tetiklenir?

Durum	Retry tetiklenir mi?
Sizin endpoint’iniz HTTP `2xx` döndü	Başarılı kabul edilir
HTTP `3xx` redirect	Takip edilmez, başarısız sayılır
HTTP `4xx` (sizin tarafta hata)	Retry edilir — handler’ınız muhtemelen geçici bir kontrol bug’ı yaşıyor
HTTP `5xx` (sizin sunucu hatası)	Retry edilir
Network timeout (15sn)	Retry edilir
TLS handshake / DNS hatası	Retry edilir

4xx’de retry niçin? Eğer endpoint’iniz bir olayı yanlışlıkla 400 dönerse (örn. transaction_id’yi DB’de bulamadığı için), Payven 5 deneme boyunca tekrarlar. Bu deneme süresinde DB sync olabilir veya konfigürasyonunuzu düzeltebilirsiniz. Ek not: olay almak istemediğiniz tipler için subscription’a hiç eklemeyin — hiç gönderilmemesi 4xx döndürmekten daha temizdir.

Timeout

Her teslim isteği için 15 saniye timeout uygulanır. Bu süreyi aşan istekler timeout sayılır ve retry edilir. Endpoint’iniz uzun süren bir iş yapacaksa:

app.post("/webhooks/payven", async (req, res) => {
  // 1. İmzayı doğrula (hızlı)
  if (!verify(req)) return res.status(401).end();

  // 2. Olayı bir queue'ya at, hemen 200 dön
  await queue.publish({ topic: "payven-webhook", payload: req.body });

  // 3. ✓ 15sn'den çok önce ack
  res.status(200).end();
});

// Worker async işler:
// queue.consume("payven-webhook", processEvent);

Manuel replay

Konsol → Webhook Teslim Logları ekranından bir teslimin Tekrar Gönder butonuyla manuel replay yapabilirsiniz. Replay edilen olay aynı X-Payven-Event-Id ile gelir; idempotent handler’ınız bunu zaten işlenmiş olarak görüp duplicate işlem yapmaz. Senaryolar:

Sizin endpoint’iniz down idi → eski olayları replay ederek yetiştirin
Bir bug nedeniyle olayları yanlış işlediniz → fix sonrası replay edip yeniden işleyin
Yeni bir feature için historical event’leri yeniden tüketmek istiyorsunuz

Subscription başına retry sayısı

Default max_retry_count: 5’tir. Yüksek hassasiyet gerektiren entegrasyonlar (örn. ERP) için daha fazla retry isterseniz subscription oluşturma / güncelleme sırasında bu değeri ayarlayabilirsiniz:

curl -X POST https://vpos.payven.com.tr/api/v1/webhook-subscriptions \
  -H "Authorization: Bearer $PAYVEN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url":             "https://erp.example.com/webhooks/payven",
    "events":          ["payment.completed", "refund.completed"],
    "max_retry_count": 10
  }'

max_retry_count 0-20 arasında kabul edilir. Üst sınır aşılırsa 422 validation_failed.

En iyi pratikler

Hızlı yanıt verin — 15sn’den çok önce 200 dönün. Long-running işleri queue’ya atın.

Idempotent yazın — X-Payven-Event-Id’yi DB’de tut ve duplicate’leri ack edip skip edin.

HTTP 2xx mantığına saygı gösterin — başarılı işleme 200, başarısız (retry isteyen) durumlara 5xx dönün; deliberate retry isteğinizde 4xx kullanmaktan kaçının.

Production’da loglayın — gelen her olayın event_id, delivery_id, body’sini saklayın; debug için kritik.

Sırasız geldiklerini varsayın — payment.completed refund.completed’tan sonra gelebilir (retry kuyruğundan çıkış sırası). created_at veya transaction.status ile durumu yeniden doğrulayın.

Genel Bakış

Ödeme Akışları

Sorgulamalar

Akıllı Yönlendirme

Mutabakat

Webhook'lar

Raporlama & İzleme

Test

Hata Kodları

Yeniden deneme programı

Hangi durumlarda retry tetiklenir?

Timeout

Manuel replay

Subscription başına retry sayısı

En iyi pratikler

​Yeniden deneme programı

​Hangi durumlarda retry tetiklenir?

​Timeout

​Manuel replay

​Subscription başına retry sayısı

​En iyi pratikler

Yeniden deneme programı

Hangi durumlarda retry tetiklenir?

Timeout

Manuel replay

Subscription başına retry sayısı

En iyi pratikler