Die Supabase-Integration versendet Ihre E-Mails aus Supabase Auth über Notifuse und überträgt neue Nutzer in Ihre Kontakte.
Überblick
Sie besteht aus zwei Teilen:
- Auth Email Hook: versendet die Transaktions-E-Mails für Authentifizierungsereignisse (Registrierung, Magic Link, Passwort-Wiederherstellung usw.)
- Before User Created Hook: fügt neue Supabase-Nutzer zu Ihren Notifuse-Kontakten hinzu
Konfiguration
Gehen Sie zu Einstellungen → Integrationen, klicken Sie auf Integration hinzufügen und wählen Sie dann Supabase unter Verbundene Apps.
Voraussetzungen
Sie brauchen:
- Einen Notifuse-Arbeitsbereich mit den nötigen Berechtigungen
- Ein Supabase-Projekt
- Mindestens eine in Notifuse eingerichtete E-Mail-Integration (für den Versand der Transaktions-E-Mails)
Auth Email Hook
Mit dem Auth Email Hook gehen Ihre eigenen Authentifizierungs-E-Mails über Notifuse hinaus, anstelle der Standard-E-Mails von Supabase.
Einrichtung
- Öffnen Sie in Ihrem Supabase-Dashboard die Supabase Auth Hooks und dort die Einstellungen des Auth Email Hook
- Fügen Sie einen neuen Hook hinzu
- Wählen Sie den Typ „HTTPS“
- Klicken Sie auf „Generate a secret“ und kopieren Sie den Wert in die Notifuse-Integration
- Speichern Sie die Integration, damit der von Notifuse erzeugte Webhook-Endpunkt angezeigt wird
- Fügen Sie den Webhook-Endpunkt in Ihren Supabase-Hook ein und speichern Sie
Standardvorlagen
Wenn Sie die Supabase-Integration zum ersten Mal speichern, legt Notifuse für jede E-Mail-Art eine Standardvorlage an. Diese Vorlagen:
- sind als von der Integration verwaltet gekennzeichnet (und lassen sich nicht löschen)
- enthalten alle nötigen Liquid-Variablen von Supabase
- lassen sich an Ihre Marke anpassen
Vorlagenvariablen
Alle Vorlagen für Supabase-Auth-E-Mails haben Zugriff auf diese Variablen:
{# User information #}
{{ user.id }}
{{ user.email }}
{{ user.phone }}
{{ user.email_new }} {# Only for email change #}
{# Email data #}
{{ email_data.token }} {# OTP code (for display, not URLs) #}
{{ email_data.token_hash }} {# Hashed token for verification URLs #}
{{ email_data.token_new }} {# For secure email changes #}
{{ email_data.token_hash_new }} {# For secure email changes #}
{{ email_data.redirect_to }} {# Where to redirect after verification #}
{{ email_data.site_url }} {# Your Supabase auth URL #}
{{ email_data.email_action_type }} {# Type: signup, recovery, magiclink, etc. #}
Format der Bestätigungs-URL
Bestätigungslinks müssen genau dieses Format haben, damit sie mit GoTrue, dem Auth-System von Supabase, funktionieren:
{{ email_data.site_url }}/verify?token={{ email_data.token_hash }}&type={{ email_data.email_action_type }}&redirect_to={{ email_data.redirect_to }}
Daraus entsteht eine URL wie diese:
https://yourproject.supabase.co/auth/v1/verify?token=abc123...&type=signup&redirect_to=https://yourapp.com
Verwenden Sie in der URL token_hash, nicht token. Die Variable token dient dazu, OTP-Codes in E-Mails zur erneuten Authentifizierung anzuzeigen.
Beispielvorlage
Eine Vorlage zur Bestätigung der Registrierung mit dem richtigen URL-Format:
<mjml>
<mj-body>
<mj-section>
<mj-column>
<mj-text font-size="20px" color="#F45E43" font-family="Helvetica"> Welcome! </mj-text>
<mj-text font-size="16px" color="#555" font-family="Helvetica">
Please confirm your email address by clicking the link below:
</mj-text>
<mj-button
href="{{ email_data.site_url }}/verify?token={{ email_data.token_hash }}&type={{ email_data.email_action_type }}&redirect_to={{ email_data.redirect_to }}"
background-color="#F45E43"
color="white"
>
Confirm Email
</mj-button>
<mj-text font-size="14px" color="#555" font-family="Helvetica">
If you did not sign up for this account, you can ignore this email.
</mj-text>
</mj-column>
</mj-section>
</mj-body>
</mjml>
Before User Created Hook
Der Before User Created Hook fügt neue Supabase-Nutzer zu Ihren Notifuse-Kontakten hinzu.
Einrichtung
- Öffnen Sie den Bereich Hook vor Benutzererstellung im Formular der Supabase-Integration
- Erzeugen Sie in Supabase einen Webhook-Schlüssel (einen anderen als für den Auth Email Hook)
- Fügen Sie den Schlüssel in das Formular der Supabase-Integration in Notifuse ein
- (Optional) Wählen Sie eine Kontaktliste, in die neue Nutzer aufgenommen werden
- (Optional) Lehnen Sie Wegwerf-E-Mail-Adressen ab (z. B. @yopmail.com)
Feldzuordnung
Felder von Supabase-Nutzern werden diesen Kontaktfeldern in Notifuse zugeordnet:
| Supabase-Feld | Notifuse-Feld |
|---|---|
email | email |
id | external_id |
phone | phone |
user_metadata | Wählbares benutzerdefiniertes JSON-Feld (optional) |
In den Einstellungen der Integration legen Sie fest, welches benutzerdefinierte JSON-Feld (1 bis 5) die user_metadata von Supabase erhält. Wählen Sie keines, werden die user_metadata nicht übertragen.
Fehlerbehandlung
Der Before User Created Hook blockiert nie eine Registrierung in Ihrer Anwendung. In diesen Fällen wird der Fehler protokolliert und die Registrierung läuft weiter:
- Das Anlegen oder Aktualisieren des Kontakts schlägt fehl
- Die eingestellte Kontaktliste wurde gelöscht
Sicherheit
Prüfung der Webhook-Signatur
Notifuse prüft jeden Supabase-Webhook anhand seiner HMAC-SHA256-Signatur und weist alle mit ungültiger Signatur ab. So verarbeitet Notifuse nur Anfragen aus Ihrem Supabase-Projekt.
Verschlüsselung
Die Schlüssel für Webhook-Signaturen liegen in der Datenbank von Notifuse mit AES-256 verschlüsselt.
Testen
Auth-E-Mails testen
- Lösen Sie in Ihrer Anwendung einen Authentifizierungsablauf aus (z. B. eine Registrierung)
- Prüfen Sie in den Notifuse-Protokollen, ob der Webhook angekommen ist
- Sehen Sie im Posteingang des Empfängers nach der E-Mail
Nutzersynchronisierung testen
- Legen Sie in Ihrem Supabase-Projekt einen neuen Nutzer an
- Gehen Sie in Notifuse zu Kontakte
- Suchen Sie nach der E-Mail-Adresse des Nutzers, um zu prüfen, ob er hinzugefügt wurde
- Wenn Sie eine Ziel-Liste eingestellt haben, prüfen Sie, ob der Nutzer darin steht
Fehlerbehebung
E-Mails werden nicht versendet
Prüfen Sie Folgendes:
- Ist ein Hook-Geheimnis im Bereich Hook zum E-Mail-Versand in Notifuse gespeichert?
- Ist der Schlüssel für die Webhook-Signatur in Supabase und in Notifuse korrekt?
- Ist in Ihrem Arbeitsbereich ein E-Mail-Anbieter für Transaktions-E-Mails eingerichtet?
- Sehen Sie in den Notifuse-Protokollen nach Fehlermeldungen
Nutzer werden nicht synchronisiert
Prüfen Sie Folgendes:
- Ist ein Hook-Geheimnis im Bereich Hook vor Benutzererstellung in Notifuse gespeichert?
- Ist der Schlüssel für die Webhook-Signatur in Supabase und in Notifuse korrekt?
- Sehen Sie in den Notifuse-Protokollen nach Fehlermeldungen
- Denken Sie daran: Fehler im Before User Created Hook werden protokolliert, verhindern aber keine Registrierung
Fehler wegen ungültiger Signatur
Meist bedeutet das:
- Der Signaturschlüssel in Notifuse stimmt nicht mit dem in Supabase überein
- Die Webhook-URL enthält falsche Parameter
workspace_idoderintegration_id - Sie testen mit einem Werkzeug wie Postman ohne den richtigen Signatur-Header
So beheben Sie es:
- Erzeugen Sie den Signaturschlüssel in Supabase neu
- Kopieren Sie den neuen Schlüssel nach Notifuse
- Verwenden Sie genau die Webhook-URL, die Notifuse angibt
Verhalten bei einer Änderung der E-Mail-Adresse
Der Ablauf „secure email change“ von Supabase verschickt zwei E-Mails:
- An die bisherige E-Mail-Adresse: verwendet
template_mappings.email_change_current- Verfügbare Variablen:
user.email,user.email_new,email_data.token_hash_new - Bestätigungs-URL:
{{ email_data.site_url }}/verify?token={{ email_data.token_hash_new }}&type=email_change&redirect_to={{ email_data.redirect_to }}
- Verfügbare Variablen:
- An die neue E-Mail-Adresse: verwendet
template_mappings.email_change_new- Verfügbare Variablen:
user.email,user.email_new,email_data.token_hash - Bestätigungs-URL:
{{ email_data.site_url }}/verify?token={{ email_data.token_hash }}&type=email_change&redirect_to={{ email_data.redirect_to }}
- Verfügbare Variablen:
Aus Gründen der Abwärtskompatibilität sind die Token-Namen von Supabase wenig intuitiv:
token_hash_newgilt für die bisherige E-Mail-Adressetoken_hashgilt für die neue E-Mail-Adresse
Die Änderung ist erst abgeschlossen, wenn beide E-Mails bestätigt sind. Notifuse erkennt sichere Adressänderungen und schickt jeder Adresse das richtige Token.
Erweiterte Konfiguration
Eigene Logik für die Kontaktliste
Um die Liste nach anderen Regeln zu wählen (zum Beispiel nach Nutzer-Metadaten):
- Lassen Sie die Ziel-Liste in den Einstellungen der Integration leer
- Gruppieren Sie die Nutzer mit Notifuse-Segmenten
- Legen Sie eine Automatisierung an, die beim Hinzufügen neuer Kontakte startet
E-Mails anpassen
Sie können jede von der Integration verwaltete Vorlage bearbeiten:
- Farben, Schriften und Layout anpassen
- Ihr Logo und weitere Elemente Ihrer Marke einfügen
- Den Text ändern, wobei die Vorlagenvariablen erhalten bleiben
- UTM-Parameter für das Tracking ergänzen
Von der Integration verwaltete Vorlagen lassen sich nicht löschen, alles darin lässt sich aber ändern.
Einschränkungen
- Von der Integration verwaltete Vorlagen lassen sich nicht löschen (aber bearbeiten)
- Jedes Supabase-Projekt braucht in Notifuse eine eigene Integration
- Der Before User Created Hook wird nur bei der Registrierung neuer Nutzer ausgelöst (nicht für bestehende Nutzer)
- Die Vorlagenvariablen gibt Supabase vor, sie lassen sich nicht ändern
Bewährte Vorgehensweisen
- Richten Sie die Integration zuerst in einem Arbeitsbereich für die Entwicklung ein, bevor Sie live gehen.
- Betrachten Sie die Standardvorlagen als Ausgangspunkt und passen Sie sie an Ihre Marke an.
- Sehen Sie regelmäßig in die Notifuse-Protokolle, um sicherzugehen, dass die Webhooks verarbeitet werden.
- Gruppieren Sie Nutzer lieber mit Segmenten als mit statischen Listen.
- Behandeln Sie die Schlüssel für Webhook-Signaturen wie Passwörter und committen Sie sie nie in die Versionsverwaltung.
