Stripe-Webhooks: Automatische E-Mail-Sprache per Währung erkennen

Ein internationaler SaaS-Anbieter stolperte über einen hartnäckigen Bug: E-Mails von Stripe-Webhooks wurden monatelang auf Japanisch verschickt – selbst an englischsprachige Kunden. Die Ursache lag nicht in einer fehlerhaften Logik, sondern in der Annahme, dass die Währung der beste Indikator für die gewünschte Sprache sei. Doch wie lässt sich die Sprache eines Nutzers ohne aufwendige Datenbankabfragen oder API-Calls zuverlässig ermitteln?

Warum die Währung oft die beste Sprachindikation ist

Bei der Internationalisierung eines SaaS-Produkts stellt sich schnell die Frage: Woher weiß das System, in welcher Sprache eine E-Mail an den Nutzer versendet werden soll? Traditionelle Ansätze wie eine language-Spalte in der Datenbank oder das Abfragen der preferred_locales über die Stripe-API bergen Nachteile:

• Datenbankabhängige Lösung: Erfordert eine Migration und lässt bestehende Nutzer zunächst ohne Sprachpräferenz – bis eine manuelle Nachbearbeitung erfolgt.
• Stripe-API-Integration: Führt zu zusätzlichen API-Aufrufen pro E-Mail und bietet keine Garantie, dass die preferred_locales überhaupt gesetzt sind.

Die pragmatische Alternative: Die Währung aus dem Stripe-Webhook-Ereignis auslesen. Da jede Zahlungstransaktion eine Währung enthält, die sich seit dem Kauf nicht mehr ändert, lässt sich daraus zuverlässig die Sprache ableiten. USD steht für englischsprachige Nutzer, während alle anderen Währungen (z. B. JPY, EUR) auf Japanisch verweisen – ein Kompromiss, der in der Praxis funktioniert, da kaum englischsprachige Nutzer in JPY zahlen und umgekehrt.

Einfache Implementierung mit lang_from_currency

Die gesamte Logik lässt sich in einer einzigen Funktion zusammenfassen:

/**
 * Ermittelt die Anzeigesprache basierend auf der Stripe-Währung.
 * @param string $currency Währungscode (z. B. 'usd', 'jpy')
 * @return string Sprachcode ('en' oder 'ja')
 */
function lang_from_currency(string $currency): string {
    $en_currencies = ['usd']; // USD → Englisch
    return in_array(strtolower($currency), $en_currencies, true) ? 'en' : 'ja';
}

Diese Funktion wird in allen vier relevanten Stripe-Webhook-Ereignissen eingesetzt:

• `checkout.session.completed` (Kaufbestätigung): $checkout_lang = lang_from_currency($session['currency'] ?? 'jpy');
• `invoice.payment_succeeded` (Zahlungserfolg): $renewal_lang = lang_from_currency($invoice['currency'] ?? 'jpy');
• `invoice.payment_failed` (Zahlungsfehler): $failed_lang = lang_from_currency($invoice['currency'] ?? 'jpy');
• `customer.subscription.updated` (Planänderung): $changed_lang = lang_from_currency($sub_currency);

Ein Fallback auf 'jpy' stellt sicher, dass selbst bei fehlenden Währungsdaten eine sinnvolle Sprache gewählt wird.

Das versteckte Problem: mb_language und MIME-kodierte Betreffzeilen

Nicht nur die Sprache der E-Mail-Inhalte, sondern auch die Kodierung des Betreffs spielt eine entscheidende Rolle für die Zustellbarkeit. PHP’s mb_send_mail() nutzt die Funktion mb_language(), um die Kodierung der Betreffzeile festzulegen:

• `mb_language('Japanese')`: Kodiert den Betreff in ISO-2022-JP (JIS X 0208), was zu Problemen führt, wenn der Betreff eigentlich auf Englisch ist. Gmail und Outlook bewerten solche E-Mails als Spam.
• `mb_language('uni')`: Kodiert den Betreff in UTF-8 Base64 (RFC 2047-konform), was für mehrsprachige Inhalte besser geeignet ist.

Die Lösung: mb_language() muss dynamisch an die Sprache der E-Mail angepasst werden:

function send_license_email($email, $client_name, $key, $plan, $period, $lang = 'ja') {
    mb_language($lang === 'en' ? 'uni' : 'Japanese');
    // Betreff und Inhalt basierend auf $lang
}

Dieser Ansatz ist seit PHP 7.2 verfügbar und stellt sicher, dass die Betreffzeile korrekt kodiert wird – unabhängig von der Sprache.

Warum ein datenbankfreier Ansatz langfristig überzeugt

Der größte Vorteil dieser Lösung liegt in ihrer Einfachheit und Wartbarkeit:

• Keine Datenbankmigrationen: Die gesamte Logik befindet sich in einer einzigen Datei (webhook.php).
• Automatische Korrektur für bestehende Nutzer: Selbst Nutzer, die vor Monaten einen Kauf getätigt haben, erhalten ihre nächste Rechnung in der richtigen Sprache.
• Geringere Fehleranfälligkeit: Weniger Abhängigkeiten von externen Systemen (z. B. Stripe-API) reduzieren die Komplexität.

Ein datenbankbasierter Ansatz hätte hingegen eine manuelle Nachbearbeitung bestehender Nutzer erfordert – mit dem Risiko, dass einige Nutzer dauerhaft falsche Sprachen zugewiesen bekommen.

Drei Prinzipien für die Internationalisierung von Webhooks

Aus dieser Erfahrung lassen sich drei allgemeingültige Muster für die Internationalisierung von Webhook-basierten Systemen ableiten:

1. Nutze starke Signale aus dem Webhook-Payload: Wenn ein Signal wie die Währung bereits im Ereignis enthalten ist und sich nicht mehr ändert, ist es die effizienteste Lösung für die Sprachauswahl. Dies spart Datenbankabfragen und API-Calls.

1. Achte auf korrekte MIME-Kodierung: Die Betreffzeile einer E-Mail muss in der richtigen Kodierung versendet werden, um Spam-Filter zu umgehen. mb_language('uni') für nicht-japanische Sprachen ist hier der Schlüssel.

1. Vermeide unnötige Zustandsverwaltung: Eine stateless-Architektur, die auf bestehenden Daten im Webhook-Payload aufbaut, reduziert die Wartungskosten und die Fehleranfälligkeit.

Langfristig zahlt sich ein solcher Ansatz aus – besonders, wenn das SaaS-Produkt weiter wächst und neue Märkte erschließt. Die Währung als Sprachindikator mag auf den ersten Blick simpel wirken, doch sie ist ein robustes und skalierbares Signal, das viele Fallstricke vermeidet.