Stripe Webhook'larından Çok Dilli E-postalar
Bir SaaS'ı küresel ölçekte büyütmenin gizli tuzakları vardır. Biz bir tanesini Stripe webhook'larımızda bulduk.
Sistemimiz; satın alma onaylarını, yenilemeleri ve hata bildirimlerini İngilizce konuşan kullanıcılara Japonca olarak gönderiyordu. Bu hata, sessiz kaldığı için aylarca fark edilmeden yaşadı.
Sorunu, dili para biriminden çıkararak çözdük.
Üç tasarım seçeneğini inceledik:
- Seçenek A: Dili veritabanında saklamak. Bu, eski kullanıcılar için migrasyonlar ve veri doldurma (backfill) işlemleri gerektirir.
- Seçenek B: Stripe API'den çekmek. Bu, ekstra API çağrıları ekler ve birçok müşteri tercih ettiği yerel ayarı (locale) belirlemez.
- Seçenek C: Webhook payload'undaki para birimini kullanmak. Bu yöntem ücretsizdir, veritabanı değişikliği gerektirmez ve mevcut kullanıcılar için anında çalışır.
Seçenek C'yi seçtik. Para birimi, satın alma anında sabit bir sinyaldir. Eğer bir kullanıcı USD ile ödeme yapıyorsa, İngilizce alır. Eğer JPY ile ödeme yapıyorsa, Japonca alır.
Mantık basit:
function lang_from_currency(string $currency): string {
$en_currencies = ['usd'];
return in_array(strtolower($currency), $en_currencies, true) ? 'en' : 'ja';
}
Bu, dört ana Stripe olayı için de çalışır:
- checkout.session.completed
- invoice.payment_succeeded
- invoice.payment_failed
- customer.subscription.updated
Ayrıca PHP ile ilgili teknik bir tuzak da bulduk.
mb_language('Japanese') kullanmak, konu başlıklarını ISO-2022-JP ile kodlar. Bu ayarla İngilizce bir konu başlığı gönderirseniz, Gmail ve Outlook bunu garip bir kodlama olarak algılar. Bu da spam puanınızı yükseltir.
Çözüm, kodlamayı dile göre değiştirmektir:
mb_language($lang === 'en' ? 'uni' : 'Japanese');
'uni' kullanmak UTF-8 Base64 kullanır. Bu, e-postalarınızın spam klasörüne düşmesini engeller.
Bu düzeltmeden çıkarılan üç ders:
- Event payload'unu kullanın. Eğer veri zaten webhook içindeyse veritabanınıza dokunmayın. Bu, riski ve bakım ihtiyacını azaltır.
- Kodlamanıza dikkat edin. Birden fazla dili destekliyorsanız, spam filtrelerinden kaçınmak için konu başlığı kodlamanızın içerikle eşleştiğinden emin olun.
- Sabit kodlanmış (hardcoded) değerleri denetleyin. Uluslararası pazara açıldığınızda, bildirim fonksiyonlarınızın sabit dil ayarları içerip içermediğini kontrol edin.
Durumsuz (stateless) bir tasarım, sisteminizi bakımının daha kolay ve bozulmasının daha zor hale getirir.