Zum Inhalt springen

Integrationen

Supabase

Supabase Auth mit Notifuse verbinden, für Authentifizierungs-E-Mails und die Synchronisierung von Nutzern.

Supabase-Integration

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:

  1. Auth Email Hook: versendet die Transaktions-E-Mails für Authentifizierungsereignisse (Registrierung, Magic Link, Passwort-Wiederherstellung usw.)
  2. 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

  1. Öffnen Sie in Ihrem Supabase-Dashboard die Supabase Auth Hooks und dort die Einstellungen des Auth Email Hook
  2. Fügen Sie einen neuen Hook hinzu
  3. Wählen Sie den Typ „HTTPS“
  4. Klicken Sie auf „Generate a secret“ und kopieren Sie den Wert in die Notifuse-Integration
  5. Speichern Sie die Integration, damit der von Notifuse erzeugte Webhook-Endpunkt angezeigt wird
  6. Fügen Sie den Webhook-Endpunkt in Ihren Supabase-Hook ein und speichern Sie
Supabase Auth Hooks Konfiguration eines Supabase Auth Hook Notifuse-Integration Notifuse-Endpunkte

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
Notifuse-Vorlagen für Supabase

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

  1. Öffnen Sie den Bereich Hook vor Benutzererstellung im Formular der Supabase-Integration
  2. Erzeugen Sie in Supabase einen Webhook-Schlüssel (einen anderen als für den Auth Email Hook)
  3. Fügen Sie den Schlüssel in das Formular der Supabase-Integration in Notifuse ein
  4. (Optional) Wählen Sie eine Kontaktliste, in die neue Nutzer aufgenommen werden
  5. (Optional) Lehnen Sie Wegwerf-E-Mail-Adressen ab (z. B. @yopmail.com)

Feldzuordnung

Felder von Supabase-Nutzern werden diesen Kontaktfeldern in Notifuse zugeordnet:

Supabase-FeldNotifuse-Feld
emailemail
idexternal_id
phonephone
user_metadataWä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

  1. Lösen Sie in Ihrer Anwendung einen Authentifizierungsablauf aus (z. B. eine Registrierung)
  2. Prüfen Sie in den Notifuse-Protokollen, ob der Webhook angekommen ist
  3. Sehen Sie im Posteingang des Empfängers nach der E-Mail

Nutzersynchronisierung testen

  1. Legen Sie in Ihrem Supabase-Projekt einen neuen Nutzer an
  2. Gehen Sie in Notifuse zu Kontakte
  3. Suchen Sie nach der E-Mail-Adresse des Nutzers, um zu prüfen, ob er hinzugefügt wurde
  4. 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_id oder integration_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:

  1. 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 }}
  2. 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 }}

Aus Gründen der Abwärtskompatibilität sind die Token-Namen von Supabase wenig intuitiv:

  • token_hash_new gilt für die bisherige E-Mail-Adresse
  • token_hash gilt 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):

  1. Lassen Sie die Ziel-Liste in den Einstellungen der Integration leer
  2. Gruppieren Sie die Nutzer mit Notifuse-Segmenten
  3. 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

  1. Richten Sie die Integration zuerst in einem Arbeitsbereich für die Entwicklung ein, bevor Sie live gehen.
  2. Betrachten Sie die Standardvorlagen als Ausgangspunkt und passen Sie sie an Ihre Marke an.
  3. Sehen Sie regelmäßig in die Notifuse-Protokolle, um sicherzugehen, dass die Webhooks verarbeitet werden.
  4. Gruppieren Sie Nutzer lieber mit Segmenten als mit statischen Listen.
  5. Behandeln Sie die Schlüssel für Webhook-Signaturen wie Passwörter und committen Sie sie nie in die Versionsverwaltung.