Webhooks

Webhooks, ödeme sonucunun sistemler arası güvenli senkronizasyonu için kritik katmandır.

Temel prensip

• Kullanıcı dönüş URL'si bilgilendirme içindir.
• Nihai durum için webhook event'i esas alınır.

Önerilen handler akışı

export async function handleWebhook(rawBody: string, signature: string) {
  // 1) İmza doğrulama
  // 2) Event parse
  // 3) Idempotency check (eventId)
  // 4) Domain state transition
  // 5) 2xx response
}

Güvenlik ve dayanıklılık

• İmza doğrulaması başarısızsa event'i reddet (401/403).
• Aynı eventId ikinci kez gelirse yeniden işlem yapma.
• Handler içinde dış servis çağrılarını kısa timeout ile sınırla.

Olay örnekleri

• payment.succeeded
• payment.updated (ör. requires_payment_method, requires_action, processing)
• refund.created
• checkout_session.completed

Operasyonel öneri

Webhook tüketimini kuyruk tabanlı bir işleyiciye (queue worker) devretmek, pik trafikte veri kaybı riskini azaltır.