E-mails Multilíngues a partir de Webhooks do Stripe
Escalar um SaaS globalmente tem armadilhas ocultas. Encontramos uma em nossos webhooks do Stripe.
Nosso sistema enviava confirmações de compra, renovações e avisos de falha em japonês para usuários que falam inglês. Esse bug persistiu por meses porque ele era silencioso.
Resolvemos isso inferindo o idioma a partir da moeda.
Analisamos três opções de design:
- Opção A: Armazenar o idioma no banco de dados. Isso requer migrações e backfills para usuários antigos.
- Opção B: Buscar da API do Stripe. Isso adiciona chamadas de API extras e muitos clientes não definem um local de preferência.
- Opção C: Usar a moeda no payload do webhook. Isso é gratuito, não requer alterações no banco de dados e funciona imediatamente para usuários existentes.
Escolhemos a Opção C. A moeda é um sinal fixo no momento da compra. Se um usuário paga em USD, ele recebe inglês. Se paga em JPY, recebe japonês.
A lógica é simples:
function lang_from_currency(string $currency): string {
$en_currencies = ['usd'];
return in_array(strtolower($currency), $en_currencies, true) ? 'en' : 'ja';
}
Isso funciona para os quatro principais eventos do Stripe:
- checkout.session.completed
- invoice.payment_succeeded
- invoice.payment_failed
- customer.subscription.updated
Também encontramos uma armadilha técnica com o PHP.
Usar mb_language('Japanese') codifica os assuntos em ISO-2022-JP. Se você enviar um assunto em inglês com essa configuração, o Gmail e o Outlook o verão como uma codificação estranha. Isso aumenta sua pontuação de spam.
A correção é alternar a codificação com base no idioma:
mb_language($lang === 'en' ? 'uni' : 'Japanese');
Usar 'uni' utiliza UTF-8 Base64. Isso mantém seus e-mails fora da pasta de spam.
Três lições desta correção:
- Use o payload do evento. Se os dados já estão no webhook, não toque no seu banco de dados. Isso reduz o risco e a manutenção.
- Atenção à sua codificação. Se você suporta múltiplos idiomas, garanta que a codificação do assunto corresponda ao conteúdo para evitar filtros de spam.
- Audite valores fixos (hardcoded). Quando você se tornar internacional, verifique se suas funções de notificação possuem configurações de idioma fixas no código.
Um design stateless torna seu sistema mais fácil de manter e mais difícil de quebrar.