> ## Documentation Index
> Fetch the complete documentation index at: https://www.notifuse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Supabase

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

![Supabase-Integration](https://www.notifuse.com/docs/assets/integrations/supabase.png)

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](https://supabase.com/dashboard/project/_/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](https://www.notifuse.com/docs/assets/screenshots/supabase/supabase_settings.png)

![Konfiguration eines Supabase Auth Hook](https://www.notifuse.com/docs/assets/screenshots/supabase/supabase_hook.png)

![Notifuse-Integration](https://www.notifuse.com/docs/assets/screenshots/supabase/supabase_notifuse.png)

![Notifuse-Endpunkte](https://www.notifuse.com/docs/assets/screenshots/supabase/supabase_endpoints.png)

### 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](https://www.notifuse.com/docs/assets/screenshots/supabase/supabase_templates.png)

### Vorlagenvariablen

Alle Vorlagen für Supabase-Auth-E-Mails haben Zugriff auf diese Variablen:

```liquid
{# 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:

```liquid
{{ 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
<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-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

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.

## Weitere Dokumentation

- [Supabase Auth Hooks: Send Email Hook](https://supabase.com/docs/guides/auth/auth-hooks/send-email-hook)
- [Supabase Auth Hooks: Before User Created Hook](https://supabase.com/docs/guides/auth/auth-hooks/before-user-created-hook)
- [E-Mail-Vorlagen in Notifuse](https://www.notifuse.com/de/docs/features/templates.md)
- [Kontakte in Notifuse](https://www.notifuse.com/de/docs/features/contacts.md)
- [Listen in Notifuse](https://www.notifuse.com/de/docs/features/lists.md)
