Webhooks

Bu sayfa webhook bildirimlerini anlatır. Olay tiplerini, gövdeyi, imza doğrulamayı ve yeniden deneme kurallarını burada görürsünüz.

LydiaGate, bir ödeme ya da iade sonuçlandığında sunucunuza bir webhook gönderir. Teknik olarak sizin belirlediğiniz adrese yapılan bir HTTPS POST isteğidir. Gövde küçüktür ve yalnız olay tipiyle ödeme kodunu taşır. Webhook bir tetikleyicidir, sonucun kendisi değildir. Kesin durumu ve tutarları GET /v1/payments/{paymentCode} ile çekersiniz. Ayrıntı: Ödeme Sorgula.

Olay tipleri

Olay tipi	Ne zaman gönderilir
payment.captured	Tahsilat onaylandı. Ödeme captured oldu.
payment.failed	3D Secure ya da tahsilat reddedildi. Ödeme failed oldu.
payment.expired	Süre doldu ya da 3D Secure yarıda bırakıldı. Ödeme expired oldu.
refund.approved	Bir iade ya da iptal onaylandı.
refund.declined	Bir iade ya da iptal reddedildi.
webhook.test	Panelden “Test gönder” tetiklendiğinde gönderilir. İş verisi taşımaz. Entegrasyonunuzu canlı veri olmadan sınamak içindir.

Bankanın ara adımları webhook olarak gönderilmez. Ödeme durumlarının tam listesi: Ödeme Durumları.

Not

Endpoint’inizde katı bir tip listesi tutmayın. Tanımadığınız bir type değeri aldığınızda da isteği 2xx ile onaylayın. LydiaGate zamanla yeni olay tipleri ekleyebilir. Bilinmeyen tipi sessizce onaylamak entegrasyonunuzun ileride bozulmamasını sağlar.

Not

İade ve iptal sonuçları refund.approved ve refund.declined olaylarıyla gelir. Ayrı bir payment.voided ya da payment.refunded olayı yoktur. Bir refund.approved aldığınızda ödemenin yeni durumunu sorguyla öğrenirsiniz. Banka onayı gecikebilir. Bu durumda refund.approved olayı iade isteğinizden dakikalar, hatta saatler sonra gelebilir. Bu beklenen bir davranıştır.

Gövde

Gövde kesin sonucu ya da tutarı taşımaz. Bu bilinçli bir tasarımdır. Ham banka yanıtı, kart verisi ya da başka bir hassas alan içermez. Karar vermek için her zaman ödemeyi sorgulayın.

{
  "id": "whd_a1b2c3",
  "type": "payment.captured",
  "paymentCode": "pay_7Hq2bL",
  "occurredAt": "2026-10-23T09:05:11Z"
}

Alan	Anlamı
id	Teslimat kimliği. Aynı teslimat tekrar gelebilir. Tekilleştirme için kullanılır.
type	Olay tipi. Olay tipleri tablosundaki değerlerden biri.
paymentCode	İlgili ödemenin kodu. Detayı sorgulamak için kullanın. İade olaylarında da ödemenin kodu gelir.
occurredAt	Olayın gerçekleştiği an.

webhook.test gövdesi yalnız id, type ve occurredAt taşır. Ödeme kodu yoktur:

{
  "id": "whd_1a2b3c",
  "type": "webhook.test",
  "occurredAt": "2026-10-23T09:02:33Z"
}

Başlıklar, imza doğrulama ve endpoint gereksinimleri

Başlıklar

Her teslimat X-Lydiagate-* başlıklarını taşır.

Başlık	Açıklama
X-Lydiagate-Signature	sha256=<hex> biçiminde, ham istek gövdesinin HMAC-SHA256 imzası.
X-Lydiagate-Timestamp	Olayın gerçekleştiği an, epoch saniyesi. Gövdedeki occurredAt ile aynıdır. Gönderim anı değildir. Aynı olay yeniden denendiğinde bu değer değişmez. İmzaya dahil değildir. Bu yüzden “eski istekleri reddet” kontrolü kurmayın. Yeniden denemeler saatler sonra da aynı değeri taşır. Tekrar koruması için gövdedeki id alanını kullanın.
X-Lydiagate-Delivery-Id	Teslimat kimliği. Gövdedeki id ile aynıdır. Başlık imzaya dahil değildir. Tekilleştirmede imzası doğrulanmış gövdedeki id alanını kullanın.

İmzada kullanılan secret, API anahtarından ayrı bir webhook secret’ıdır. Hesap açılışında LydiaGate sizin adınıza tanımlayabilir. Sonradan panelin Webhook Ayarları ekranından siz değiştirirsiniz. Secret’ı loglamayın, tarayıcıya ya da mobil uygulamaya göndermeyin, kod deponuzda saklamayın.

İmza doğrulama

İmza yalnız ham istek gövdesi üzerinden hesaplanır. timestamp imzaya girmez. Birleştirme yapılmaz. Karşılaştırmayı sabit zamanlı yapın. Böylece imza parça parça tahmin edilemez. Dilden bağımsız sözde kod:

rawBody    = istekte gelen ham byte'lar
signature  = header["X-Lydiagate-Signature"]

expected   = "sha256=" + lowercase_hex( HMAC_SHA256(webhookSecret, rawBody) )

# 1) İmza eşleşmeli (sabit zamanlı karşılaştırma)
if not constantTimeEquals(expected, signature):
    return 400

# 2) Tekilleştirme: kimliği imzası doğrulanmış gövdeden alın.
#    Başlık imzaya dahil değildir, değiştirilmiş olabilir.
deliveryId = parseJson(rawBody).id
if alreadyProcessed(deliveryId):
    return 200

# 3) Bildirimi ve işleme görevini aynı transaction'da kaydedin.
#    deliveryId benzersiz olsun; tekrar gelen teslimat ikinci kayıt açmaz.
saveDeliveryAndEnqueueJob(deliveryId, rawBody)
return 200

# Görev (ayrı süreç): ödemeyi GET /v1/payments ile sorgular,
# iş bitince teslimatı "işlendi" olarak işaretler.

Dikkat

İmzayı ham gövde byte’ları üzerinden hesaplayın. Gövdeyi JSON olarak ayrıştırıp yeniden yazmayın. Bu işlem alan sırasını ve boşlukları değiştirir. İmza bozulur. Çoğu web çatısında bu, ham gövdeyi doğrulamadan önce yakalamayı gerektirir.

Endpoint gereksinimleri

• Hızlı 2xx döndürün. Teslimatın toplam süre bütçesi 5 saniyedir ve bu süre LydiaGate tarafındaki hazırlıkla başlar. Endpoint’iniz imzayı doğrulayıp bildirimi kaydettikten sonra hemen 2xx dönmelidir. Aksi halde teslimat zaman aşımı sayılır ve yeniden denenir. Ağır işi yanıttan sonra yapın.
• İmzayı doğrulayın. İmzayı doğrulamadan gövdeye güvenmeyin.
• Tekrara dayanıklı olun. Aynı teslimat birden fazla gelebilir. Gövdedeki id alanıyla tekilleştirin. Teslimatı 2xx dönmeden önce kalıcı olarak kaydedin. “İşlendi” işaretini iş tamamlanınca koyun; aksi halde yanıt sonrası bir kesintide olay kaybolur. İşleme mantığınız aynı teslimatı iki kez almaya dayanıklı olmalıdır.
• Tetikleyici olarak kullanın. Bildirim gelince ödemenin detayını API’den sorgulayın ve kararınızı sorgu sonucuna göre verin.

Yeniden deneme ve teslimat

• Başarı: 2xx. Teslimat tamamlanmış sayılır.
• Kalıcı hata: 4xx yeniden denenmez. Endpoint’inizin geçerli teslimatlara 2xx döndürdüğünden emin olun.
• Yeniden deneme: 5xx ve zaman aşımı artan aralıklarla tekrar denenir: 30 saniye, 2 dakika, 10 dakika, 1 saat, 6 saat. Bu çizelge tükenince yeniden deneme durur ve teslimat bırakılır. Son deneme ilk denemeden yaklaşık 7 saat 13 dakika sonra yapılır. Teslimatın azami yaşı 24 saattir.
• Sıra garantisi yoktur. Olaylar gönderildikleri sırada gelmeyebilir. Durumu olay tipine değil, sorgu sonucuna göre belirleyin.

Not

Webhook’u yalnız bir bildirim olarak görün. Tetiklendiğinde ödemeyi sorgulayın. Bir bildirimi kaçırsanız bile durumu sorguyla kurtarırsınız. Sorgu her zaman kesin sonucu verir.

Panelden yapılandırma

Webhook adresini ve imza secret’ını İş Ortağı Paneli’nde Geliştirici → Webhook Ayarları ekranından yönetirsiniz. Bu ekranı değiştirmek için “Webhook yönetimi” yetkisi gerekir.

• Adres: https ile başlamalı ve internetten erişilebilir olmalıdır. Kurum içi bir adres kabul edilmez.
• İmza secret’ı: ilk kurulumda zorunludur. Hesap açılışında LydiaGate sizin adınıza tanımladıysa bu alanı boş bırakabilirsiniz. Sonraki düzenlemelerde boş bırakılırsa değişmez.
• Test gönder: adresinize bir webhook.test olayı gönderir. Adres erişimini ve imza doğrulamasını canlı veri olmadan sınar.
• Adresi kaldır: bildirimler durur. Secret silinmez.

Teslimatları Geliştirici → Webhook Olayları ekranından izlersiniz. Her teslimatın durumunu ve ham gövdesini görürsünüz. Gerekirse yeniden gönderirsiniz. Yeniden göndermek için de “Webhook yönetimi” yetkisi gerekir.

Webhook adresi tanımlı değilse hiçbir bildirim gönderilmez. Bu durumda ödeme durumlarını yalnız GET /v1/payments/{paymentCode} ile takip edin. Ekranların ayrıntısı: Panel Kılavuzu.