Email multilingue dai webhook di Stripe
Scalare un SaaS a livello globale presenta delle insidie nascoste. Ne abbiamo trovata una nei nostri webhook di Stripe.
Il nostro sistema inviava conferme d'acquisto, rinnovi e avvisi di errore in giapponese a utenti di lingua inglese. Questo bug è rimasto attivo per mesi perché non dava nell'occhio.
Lo abbiamo risolto deducendo la lingua dalla valuta.
Abbiamo valutato tre opzioni di progettazione:
- Opzione A: Memorizzare la lingua nel database. Ciò richiede migrazioni e backfill per gli utenti esistenti.
- Opzione B: Recuperarla tramite l'API di Stripe. Questo aggiunge chiamate API extra e molti clienti non impostano una lingua preferita.
- Opzione C: Utilizzare la valuta nel payload del webhook. È gratuita, non richiede modifiche al database e funziona immediatamente anche per gli utenti esistenti.
Abbiamo scelto l'Opzione C. La valuta è un segnale fisso al momento dell'acquisto. Se un utente paga in USD, riceve l'inglese. Se paga in JPY, riceve il giapponese.
La logica è semplice:
function lang_from_currency(string $currency): string {
$en_currencies = ['usd'];
return in_array(strtolower($currency), $en_currencies, true) ? 'en' : 'ja';
}
Funziona per tutti e quattro i principali eventi di Stripe:
- checkout.session.completed
- invoice.payment_succeeded
- invoice.payment_failed
- customer.subscription.updated
Abbiamo trovato anche un'insidia tecnica con PHP.
L'uso di mb_language('Japanese') codifica l'oggetto in ISO-2022-JP. Se invii un oggetto in inglese con questa impostazione, Gmail e Outlook lo vedranno come una codifica insolita. Questo aumenta il tuo punteggio spam.
La soluzione è cambiare la codifica in base alla lingua:
mb_language($lang === 'en' ? 'uni' : 'Japanese');
L'uso di 'uni' utilizza UTF-8 Base64. Questo evita che le tue email finiscano nella cartella spam.
Tre lezioni apprese da questa correzione:
- Usa il payload dell'evento. Se i dati sono già presenti nel webhook, non toccare il database. Riduce i rischi e la manutenzione.
- Fai attenzione alla codifica. Se supporti più lingue, assicurati che la codifica dell'oggetto corrisponda al contenuto per evitare i filtri antispam.
- Controlla i valori hardcoded. Quando ti espandi a livello internazionale, verifica se le tue funzioni di notifica hanno impostazioni della lingua hardcoded.
Un design stateless rende il tuo sistema più facile da mantenere e più difficile da rompere.