Skip to main content
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:
DenemeYaklaşık bekleme süresi
1Hemen
21 dakika sonra
35 dakika sonra
430 dakika sonra
52 saat sonra
624 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?

DurumRetry tetiklenir mi?
Sizin endpoint’iniz HTTP 2xx döndüBaşarılı kabul edilir
HTTP 3xx redirectTakip 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.